@campo-design/lint 0.0.0-stage → 0.1.0

package/src/setup.js

@@ -0,0 +1,100 @@
+// Campo's fixed setup, checked across a whole product (AGENTS.md, Web
+// Awesome: "Setup is fixed").
+//
+// Unlike the Stylelint and ESLint rules, most of these are about a product,
+// not one file: the theme classes can sit in a layout and connectColorScheme()
+// in a script, and a linter sees one file at a time. So setupFindings takes
+// every file of a product at once. `campo-lint setup` (../bin/campo-lint.js)
+// runs it on a product's folders; Campo's own docs and site check, and the
+// bench grader, run it through scripts/token-score.mjs.
+//
+//   setupThemeClass   <html class="wa-theme-default campo-wa">: both classes, somewhere
+//   setupThemeCss     @campo-design/webawesome/theme.css imported
+//   setupColorScheme  connectColorScheme() called, so Web Awesome follows data-theme
+//   setupIcons        registerCampoIcons() called, so <wa-icon> draws Phosphor
+//   setupImport       each <wa-*> element used is imported from dist/components/
+//                     (in React, from @campo-design/react/<name>)
+//   setupStylesheet   Web Awesome's webawesome.css imported (Campo's CSS styles native elements)
+//   setupAutoloader   Web Awesome's autoloader (webawesome.loader.js, or its root entry, which starts it)
+//   setupPalette      a wa-palette-* or wa-brand-* class (Campo decides color)
+//   setupReactImport  a component imported from Web Awesome's own React wrappers
+//                     (dist/react/), whose types don't know Campo's contracts
+//
+// In React, setupCampo() from @campo-design/react counts for both
+// connectColorScheme() and registerCampoIcons(): it calls them.
+//
+// The first five only apply to a product that uses Web Awesome at all.
+import { reactAsElements } from './core.js';
+
+export const SETUP_RULES = ['setupThemeClass', 'setupThemeCss', 'setupColorScheme', 'setupIcons', 'setupImport', 'setupStylesheet', 'setupAutoloader', 'setupPalette', 'setupReactImport'];
+
+/** What to do about each finding, for a person or an agent reading the report. */
+export const SETUP_FIXES = {
+  setupThemeClass: 'Put class="wa-theme-default campo-wa" on <html>.',
+  setupThemeCss: "Import @campo-design/webawesome/theme.css once, in the product's entry stylesheet or script.",
+  setupColorScheme: 'Call connectColorScheme() from @campo-design/webawesome once (in React, setupCampo()), so Web Awesome follows data-theme.',
+  setupIcons: 'Call registerCampoIcons() from @campo-design/webawesome/icons once (in React, setupCampo()), so <wa-icon> draws Phosphor.',
+  setupImport: 'Import it from @awesome.me/webawesome/dist/components/<name>/<name>.js (in React, @campo-design/react/<name>).',
+  setupStylesheet: "Remove it: Campo's CSS (@campo-design/css) styles native elements.",
+  setupAutoloader: 'Import each component you use instead: Campo checks what a product imports.',
+  setupPalette: 'Remove it: Campo decides color through its tokens.',
+  setupReactImport: "Import it from @campo-design/react/<name>: its types come from Campo's contracts.",
+};
+
+// Blanks out code shown as text, keeping line breaks so line numbers stay
+// right: <code> and <pre> elements, and in Markdown, fenced blocks and inline
+// code. Docs that teach a rule ("no `!important`") quote what it forbids.
+const blank = (match) => match.replace(/[^\n]/g, ' ');
+export function withoutCode(text, file) {
+  let out = text.replace(/<(code|pre)\b[\s\S]*?<\/\1>/g, blank);
+  if (file.endsWith('.md')) out = out.replace(/^```[\s\S]*?^```/gm, blank).replace(/`[^`\n]*`/g, blank);
+  return out;
+}
+
+/**
+ * Setup findings for a whole product, from its files as [{ file, text }].
+ * Each finding is { rule, detail, file?, line? }: a missing step has no file.
+ * Code shown as text is skipped.
+ */
+export function setupFindings(entries) {
+  const findings = [];
+  const code = entries.map(({ file, text }) => ({ file, text: reactAsElements(withoutCode(text, file)) }));
+  const lineOf = (text, index) => text.slice(0, index).split('\n').length;
+  for (const { file, text } of code) {
+    for (const m of text.matchAll(/webawesome\/dist\/styles\/webawesome\.css/g)) {
+      findings.push({ rule: 'setupStylesheet', detail: 'webawesome.css', file, line: lineOf(text, m.index) });
+    }
+    for (const m of text.matchAll(/webawesome\.loader(?:\.js)?|@awesome\.me\/webawesome\/dist\/webawesome\.js|(?:from\s*|import\s*\(?\s*)['"]@awesome\.me\/webawesome['"]/g)) {
+      findings.push({ rule: 'setupAutoloader', detail: m[0], file, line: lineOf(text, m.index) });
+    }
+    for (const m of text.matchAll(/(?<![\w-])wa-(?:palette|brand)-[a-z0-9-]+/g)) {
+      findings.push({ rule: 'setupPalette', detail: m[0], file, line: lineOf(text, m.index) });
+    }
+    for (const m of text.matchAll(/@awesome\.me\/webawesome\/dist\/react\/([a-z0-9-]+)/g)) {
+      findings.push({ rule: 'setupReactImport', detail: `@awesome.me/webawesome/dist/react/${m[1]}`, file, line: lineOf(text, m.index) });
+    }
+  }
+
+  const all = code.map((c) => c.text).join('\n');
+  const tags = new Map();
+  for (const { file, text } of code) {
+    for (const m of text.matchAll(/<(wa-[a-z][a-z0-9-]*)\b/g)) if (!tags.has(m[1])) tags.set(m[1], { file, line: lineOf(text, m.index) });
+  }
+  const usesWebAwesome = tags.size > 0 || /@awesome\.me\/webawesome|@campo-design\/(?:webawesome|react)/.test(all);
+  const setupCampo = /\bsetupCampo\s*\(/.test(all);
+  if (!usesWebAwesome) return findings;
+
+  if (!(/(?<![\w-])wa-theme-default(?![\w-])/.test(all) && /(?<![\w-])campo-wa(?![\w-])/.test(all))) {
+    findings.push({ rule: 'setupThemeClass', detail: 'wa-theme-default and campo-wa on <html>' });
+  }
+  if (!/@campo-design\/webawesome\/theme\.css/.test(all)) findings.push({ rule: 'setupThemeCss', detail: '@campo-design/webawesome/theme.css' });
+  if (!setupCampo && !/\bconnectColorScheme\s*\(/.test(all)) findings.push({ rule: 'setupColorScheme', detail: 'connectColorScheme()' });
+  if (!setupCampo && !/\bregisterCampoIcons\s*\(/.test(all)) findings.push({ rule: 'setupIcons', detail: 'registerCampoIcons()' });
+  const imported = new Set(
+    [...all.matchAll(/webawesome\/dist\/(?:components|react)\/([a-z0-9-]+)\/|@campo-design\/react\/([a-z0-9-]+)/g)].map((m) => `wa-${m[1] ?? m[2]}`),
+  );
+  for (const [tag, where] of tags) {
+    if (!imported.has(tag)) findings.push({ rule: 'setupImport', detail: `<${tag}>`, ...where });
+  }
+  return findings;
+}

package/src/stylelint/index.js

@@ -0,0 +1,49 @@
+// Campo's shared Stylelint config: `extends: ['@campo-design/lint/stylelint']`.
+//
+// It holds Campo's rules only: design values come from semantic tokens, and
+// a product doesn't patch Campo. Bug-catching rules (invalid properties,
+// unknown units) are the product's own choice; add
+// stylelint-config-recommended next to it for those.
+//
+// What it allows on purpose: layout values (max-width: 65ch, grid templates,
+// breakpoints), em values, 0, %, keywords (transparent, currentColor,
+// inherit), and a local custom property for a size two rules share.
+import plugins from './plugin.js';
+import { COLOR_FUNCTIONS, TOKEN_UNITS } from '../core.js';
+
+export default {
+  plugins,
+  // A stylelint-disable must say why, after `--`: `/* stylelint-disable rule
+  // -- reason */`. A disable with no reason is how an exception becomes a habit.
+  reportDescriptionlessDisables: true,
+  rules: {
+    // Tokens only, and only the semantic tier.
+    'campo/semantic-tokens': true,
+
+    // Colors: tokens only.
+    'color-no-hex': true,
+    'color-named': 'never',
+    'function-disallowed-list': [COLOR_FUNCTIONS, { message: (name) => `Use a Campo color token, not ${name}().` }],
+
+    // Lengths and durations: tokens only, for the properties tokens exist for.
+    'declaration-property-unit-disallowed-list': [
+      TOKEN_UNITS,
+      {
+        message: (property, unit) =>
+          `Use a Campo token for ${property}, not a raw "${unit}" value. If none fits, that's a token for Campo to add.`,
+      },
+    ],
+    // The same, for a raw value routed through a local custom property.
+    'campo/no-raw-through-custom-property': true,
+    'declaration-property-value-disallowed-list': [
+      { 'font-weight': ['/^\\d+$/'] },
+      { message: (property) => `Use a Campo token for ${property}, not a raw number.` },
+    ],
+
+    // Don't patch Campo.
+    // Layer order is what lets product CSS win over Campo's; !important bypasses it.
+    'declaration-no-important': true,
+    'campo/no-wa-override': true,
+    'campo/no-color-scheme-query': true,
+  },
+};

package/src/stylelint/plugin.js

@@ -0,0 +1,153 @@
+// Campo's Stylelint rules: the ones Stylelint's built-in rules can't express.
+// ./index.js turns them on, with the built-in rules, as Campo's shared config.
+//
+// campo/semantic-tokens
+//   A var(--campo-*) that isn't a semantic token: a primitive (reaches past
+//   the tier, so a theme or redesign doesn't reach it) or a name Campo doesn't
+//   define (looks right, resolves to nothing). The message names the semantic
+//   tokens that point at a primitive.
+//
+// campo/no-raw-through-custom-property
+//   declaration-property-unit-disallowed-list stops `gap: 16px`, but not
+//   `--gap: 16px; gap: var(--gap)`: a custom property has no property type, so
+//   the unit rule can't see where its value ends up. This rule follows a local
+//   custom property (not --campo-* or --wa-*) declared in the same file to the
+//   properties that use it, and reports a raw unit there that the unit rule
+//   would have reported if it were written out. A local custom property for a
+//   size two rules share is still fine: it's reported only where it lands in a
+//   property tokens own, such as padding or gap. Same file only.
+//
+// campo/no-wa-override
+//   Declaring a --wa-* token. Campo's bridge maps every one to a Campo token;
+//   an override anywhere else bypasses Campo and breaks at the next theme
+//   change. To change how Web Awesome looks, change a Campo token.
+//
+// campo/no-color-scheme-query
+//   An @media (prefers-color-scheme). Campo's themes repoint the semantic
+//   tokens, so a screen built from them is already right in both; a query adds
+//   a second, unchecked version of the theme.
+import stylelint from 'stylelint';
+import { TOKEN_UNITS, tierProblem } from '../core.js';
+
+const {
+  createPlugin,
+  utils: { report, ruleMessages, validateOptions },
+} = stylelint;
+
+const NAMESPACE = 'campo';
+const url = (rule) => `https://github.com/jlitchfield/campo/blob/main/packages/lint/README.md#${NAMESPACE}${rule}`;
+const on = (actual) => (result, ruleName) => validateOptions(result, ruleName, { actual, possible: [true] });
+
+// ---- campo/semantic-tokens ---------------------------------------------------
+
+const semanticTokens = (() => {
+  const ruleName = `${NAMESPACE}/semantic-tokens`;
+  const messages = ruleMessages(ruleName, { rejected: (problem) => problem });
+  const rule = (primary) => (root, result) => {
+    if (!on(primary)(result, ruleName)) return;
+    const check = (node, value) => {
+      for (const m of value.matchAll(/var\(\s*(--campo-[a-z0-9-]+)/g)) {
+        const problem = tierProblem(m[1]);
+        if (problem) report({ ruleName, result, node, message: messages.rejected(problem), word: m[1] });
+      }
+    };
+    root.walkDecls((decl) => check(decl, decl.value));
+    root.walkAtRules((atRule) => check(atRule, atRule.params));
+  };
+  rule.ruleName = ruleName;
+  rule.messages = messages;
+  rule.meta = { url: url('semantic-tokens') };
+  return createPlugin(ruleName, rule);
+})();
+
+// ---- campo/no-raw-through-custom-property ------------------------------------
+
+const rawThroughCustomProperty = (() => {
+  const ruleName = `${NAMESPACE}/no-raw-through-custom-property`;
+  const messages = ruleMessages(ruleName, {
+    rejected: (property, name, unit) =>
+      `Use a Campo token for ${property}: ${name} holds a raw "${unit}" value. If none fits, that's a token for Campo to add.`,
+  });
+
+  // A number with a unit, not inside a var() name: 16px, .5rem, 200ms.
+  const RAW = /(?<![\w-])-?(?:\d*\.)?\d+(px|rem|em|ms|s)\b/g;
+  const VAR = /var\(\s*(--[\w-]+)/g;
+
+  /** Turns the unit rule's { "/regex/" | "name": units } into matchers. */
+  const matchers = (byProperty) =>
+    Object.entries(byProperty).map(([key, units]) => {
+      const test = key.startsWith('/') && key.endsWith('/') ? new RegExp(key.slice(1, -1)) : null;
+      return { matches: (prop) => (test ? test.test(prop) : prop === key), units };
+    });
+
+  // `true` uses Campo's TOKEN_UNITS; an object replaces them.
+  const rule = (primary) => (root, result) => {
+    const valid = validateOptions(result, ruleName, { actual: primary, possible: (v) => v === true || (v && typeof v === 'object') });
+    if (!valid) return;
+    const governed = matchers(primary === true ? TOKEN_UNITS : primary);
+
+    // Local custom properties with raw units in their value, and those units.
+    const raw = new Map();
+    root.walkDecls(/^--/, (decl) => {
+      if (/^--(campo|wa)-/.test(decl.prop)) return;
+      const units = [...decl.value.matchAll(RAW)].map((m) => m[1]);
+      if (units.length) raw.set(decl.prop, new Set([...(raw.get(decl.prop) ?? []), ...units]));
+    });
+    if (!raw.size) return;
+
+    root.walkDecls((decl) => {
+      if (decl.prop.startsWith('--')) return;
+      const prop = decl.prop.toLowerCase();
+      const disallowed = governed.filter((g) => g.matches(prop)).flatMap((g) => g.units);
+      if (!disallowed.length) return;
+      for (const [, name] of decl.value.matchAll(VAR)) {
+        const unit = [...(raw.get(name) ?? [])].find((u) => disallowed.includes(u));
+        if (unit) report({ ruleName, result, node: decl, message: messages.rejected(prop, name, unit), word: name });
+      }
+    });
+  };
+  rule.ruleName = ruleName;
+  rule.messages = messages;
+  rule.meta = { url: url('no-raw-through-custom-property') };
+  return createPlugin(ruleName, rule);
+})();
+
+// ---- campo/no-wa-override ----------------------------------------------------
+
+const noWaOverride = (() => {
+  const ruleName = `${NAMESPACE}/no-wa-override`;
+  const messages = ruleMessages(ruleName, {
+    rejected: (prop) =>
+      `Don't declare ${prop}: Campo's bridge maps every --wa-* token to a Campo token. Use the component's variants and appearances, or name the gap as a Campo token decision.`,
+  });
+  const rule = (primary) => (root, result) => {
+    if (!on(primary)(result, ruleName)) return;
+    root.walkDecls(/^--wa-/, (decl) => report({ ruleName, result, node: decl, message: messages.rejected(decl.prop), word: decl.prop }));
+  };
+  rule.ruleName = ruleName;
+  rule.messages = messages;
+  rule.meta = { url: url('no-wa-override') };
+  return createPlugin(ruleName, rule);
+})();
+
+// ---- campo/no-color-scheme-query ---------------------------------------------
+
+const noColorSchemeQuery = (() => {
+  const ruleName = `${NAMESPACE}/no-color-scheme-query`;
+  const messages = ruleMessages(ruleName, {
+    rejected: () =>
+      "Don't handle dark mode yourself: Campo's themes repoint the semantic tokens, so styles built from them are right in both.",
+  });
+  const rule = (primary) => (root, result) => {
+    if (!on(primary)(result, ruleName)) return;
+    root.walkAtRules((atRule) => {
+      if (/prefers-color-scheme/i.test(atRule.params)) report({ ruleName, result, node: atRule, message: messages.rejected(), word: 'prefers-color-scheme' });
+    });
+  };
+  rule.ruleName = ruleName;
+  rule.messages = messages;
+  rule.meta = { url: url('no-color-scheme-query') };
+  return createPlugin(ruleName, rule);
+})();
+
+export default [semanticTokens, rawThroughCustomProperty, noWaOverride, noColorSchemeQuery];