@campo-design/lint 0.0.0-stage → 0.1.0

package/src/core.js

@@ -0,0 +1,253 @@
+// What Campo's lint rules know about Campo, in one place.
+//
+// Both linters read this file: the Stylelint plugin (./stylelint) for CSS and
+// the ESLint plugin (./eslint) for JavaScript. Campo's own scoring
+// (scripts/token-score.mjs, behind `pnpm metrics`, the bench grader and the
+// docs and site check) reads it too. So "a raw value", "a primitive" and "a
+// Phosphor name" mean the same thing wherever Campo checks code. Change a rule
+// here, once.
+//
+// Nothing here is a hand-written list of tokens, icons or components. It reads
+// them from the Campo packages a product has installed, so a product's lint
+// always matches its Campo version:
+//   tokens      @campo-design/tokens/describe (reads the DTCG sources)
+//   icons       @campo-design/icons/names.json (Phosphor names)
+//   components  @campo-design/webawesome/contracts, and Web Awesome's own
+//               custom-elements.json for each component's attributes
+import { createRequire } from 'node:module';
+import { primitiveCssVars, tokenManifest } from '@campo-design/tokens/describe';
+import { checkUsage } from '@campo-design/webawesome/contracts';
+
+const require = createRequire(import.meta.url);
+
+// Loaded on first use, so a linter that never meets a token, icon or
+// component doesn't read the files.
+const once = (load) => {
+  let value;
+  let loaded = false;
+  return () => {
+    if (!loaded) {
+      value = load();
+      loaded = true;
+    }
+    return value;
+  };
+};
+
+// ---- Tokens ----------------------------------------------------------------
+
+const tokens = once(() => {
+  const manifest = tokenManifest().tokens;
+  const cssVarOf = Object.fromEntries(manifest.map((t) => [t.path, t.cssVar]));
+  return {
+    primitive: primitiveCssVars(),
+    semantic: new Set(manifest.filter((t) => t.tier === 'semantic').map((t) => t.cssVar)),
+    // A primitive's CSS variable → the semantic tokens that point at it.
+    useInstead: Object.fromEntries(
+      manifest.filter((t) => t.tier === 'primitive').map((t) => [t.cssVar, (t.useInstead ?? []).map((p) => cssVarOf[p])]),
+    ),
+  };
+});
+
+/** `semantic`, `primitive`, or `unknown` (a --campo-* name Campo doesn't define). */
+export function tokenTier(name) {
+  const { semantic, primitive } = tokens();
+  if (semantic.has(name)) return 'semantic';
+  if (primitive.has(name)) return 'primitive';
+  return 'unknown';
+}
+
+/** Every primitive's CSS variable. */
+export const primitives = () => [...tokens().primitive];
+
+/** The semantic tokens that point at a primitive: what to use instead. */
+export const semanticFor = (primitive) => tokens().useInstead[primitive] ?? [];
+
+/** Every --campo-* variable a value reads through var(). */
+export const campoVars = (value) => [...value.matchAll(/var\(\s*(--campo-[a-z0-9-]+)/g)].map((m) => m[1]);
+
+/** The message for a --campo-* variable that isn't a semantic token, or null if it is one. */
+export function tierProblem(name) {
+  const tier = tokenTier(name);
+  if (tier === 'semantic') return null;
+  if (tier === 'unknown') return `${name} isn't a Campo token. Check the name in @campo-design/tokens/manifest.json.`;
+  const instead = semanticFor(name);
+  const hint = instead.length ? ` Use ${instead.slice(0, 3).join(', ')}${instead.length > 3 ? ', …' : ''} instead.` : ' Use the semantic token for its role.';
+  return `${name} is a primitive. Styles use semantic tokens, so themes and redesigns reach them.${hint}`;
+}
+
+// ---- Raw values ------------------------------------------------------------
+
+const length = ['px', 'rem'];
+
+/**
+ * Which raw units each property may not take, because a token exists for it.
+ * Keys are a property name or a "/regex/", the format Stylelint's
+ * declaration-property-unit-disallowed-list takes. What stays allowed on
+ * purpose: layout values (max-width: 65ch, grid templates, breakpoints), em
+ * values (relative to the text around them), 0, % and keywords.
+ */
+export const TOKEN_UNITS = {
+  '/^(margin|padding)(-.+)?$/': length,
+  '/^(gap|row-gap|column-gap)$/': length,
+  '/^border(-.+)?-radius$/': [...length, 'em'],
+  '/^(border|outline)(-(top|right|bottom|left|block|inline)(-(start|end))?)?(-width)?$/': length,
+  'outline-offset': length,
+  '/^font(-size)?$/': length,
+  'line-height': length,
+  'letter-spacing': length,
+  '/^(box|text)-shadow$/': length,
+  '/^(transition|animation)(-duration|-delay)?$/': ['ms', 's'],
+};
+
+/** Color functions a style may not call: colors come from tokens. */
+export const COLOR_FUNCTIONS = ['rgb', 'rgba', 'hsl', 'hsla', 'hwb', 'lab', 'lch', 'oklab', 'oklch'];
+
+/** Properties that have a Campo token family: color, spacing, radius, border, type, motion, shadow. */
+export const DESIGN_PROPERTY =
+  /^(color|background(-color)?|border(-(top|right|bottom|left|block|inline)(-(start|end))?)?(-(color|width))?|border(-.+)?-radius|outline(-color|-width|-offset)?|fill|stroke|text-decoration-color|caret-color|accent-color|box-shadow|margin(-.+)?|padding(-.+)?|gap|row-gap|column-gap|font-size|font-weight|font-family|line-height|transition(-duration|-delay)?|animation(-duration|-delay)?)$/;
+
+/** A hardcoded color, px/rem length or ms/s duration. */
+export const RAW_VALUE = new RegExp(
+  `#[0-9a-f]{3,8}\\b|\\b(${COLOR_FUNCTIONS.join('|')})\\(|(?<![\\w.-])-?\\d*\\.?\\d+(px|rem|ms|s)\\b`,
+  'i',
+);
+const NAMED_COLOR = /\b(white|black|red|blue|green|gray|grey|orange|purple|yellow|pink)\b/i;
+
+/**
+ * What a design declaration's value is:
+ *   token      a semantic --campo-* variable
+ *   unknown    a --campo-* variable Campo doesn't define
+ *   primitive  a primitive --campo-* variable
+ *   raw        a hardcoded color, px/rem length, ms/s duration or numeric weight
+ *   neutral    0, %, em, keywords, other variables: nothing a token should replace
+ */
+export function classify(property, value) {
+  const vars = campoVars(value);
+  const tiers = vars.map(tokenTier);
+  if (tiers.includes('unknown')) return 'unknown';
+  if (tiers.includes('primitive')) return 'primitive';
+  if (tiers.includes('semantic')) return 'token';
+  // Strip var() fallbacks and the like before looking for raw values.
+  const bare = value.replace(/var\([^)]*\)/g, '');
+  if (RAW_VALUE.test(bare)) return 'raw';
+  if (/color|background|fill|stroke|border|outline|shadow/.test(property) && NAMED_COLOR.test(bare)) return 'raw';
+  if (property === 'font-weight' && /^\d+$/.test(bare.trim())) return 'raw';
+  return 'neutral';
+}
+
+// React turns a bare number into px for these. `lineHeight: 1.5` and
+// `fontWeight: 600` aren't lengths; the weight is caught by classify.
+const UNITLESS_PX = /^(margin|padding|gap|row-gap|column-gap|border(-.+)?-(radius|width)|border-width|outline(-width|-offset)?|font-size)/;
+
+/** A React style key (`paddingBlock`) as its CSS property (`padding-block`). */
+export const cssProperty = (key) => (key.startsWith('--') ? key : key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`));
+
+/** A number in a React style object as the CSS value React renders. */
+export const styleNumber = (property, number) => (UNITLESS_PX.test(property) && Number(number) !== 0 ? `${number}px` : String(number));
+
+// ---- Icons -----------------------------------------------------------------
+
+const icons = once(() => {
+  try {
+    return new Set(require('@campo-design/icons/names.json'));
+  } catch {
+    // @campo-design/icons isn't built (only inside the Campo repo, before
+    // `pnpm build`). Skip the icon rule rather than flag every icon.
+    return null;
+  }
+});
+
+/** Whether the Phosphor name list could be read. */
+export const iconsLoaded = () => icons() !== null;
+
+/** true or false, or null when the name list isn't available. */
+export const isPhosphorIcon = (name) => (icons() ? icons().has(name) : null);
+
+/** `<wa-icon name="…">` in HTML or a template: each name and where it starts. */
+export const iconNames = (text) => [...text.matchAll(/<wa-icon\b[^>]*?\bname=["']([a-z0-9-]+)["']/g)].map((m) => ({ name: m[1], index: m.index }));
+
+// ---- Component contracts ---------------------------------------------------
+
+const customElements = once(() => require('@awesome.me/webawesome/dist/custom-elements.json'));
+
+/**
+ * Uses of a Web Awesome component, in HTML or JSX text, with a combination its
+ * contract lists as a gap (it renders in stock Web Awesome colours, not
+ * Campo's) or a value the component doesn't have. Each is { tag, line, detail, message }.
+ */
+export function contractFindings(text) {
+  return checkUsage(withoutTemplateExpressions(text), customElements()).findings.map((f) => {
+    if (f.kind === 'gap') {
+      const combo = Object.entries(f.combo).map(([a, v]) => `${a}=${v ?? '(not set)'}`).join(' ');
+      const instead = f.gap.instead ? ` ${f.gap.instead}` : '';
+      return { tag: f.tag, line: f.line, detail: `<${f.tag}> ${combo}`, message: `<${f.tag}> ${combo} is a gap in Campo's contract: it renders in stock Web Awesome colours.${instead}` };
+    }
+    const allowed = f.allowed ? ` It takes ${f.allowed.join(', ')}.` : '';
+    return { tag: f.tag, line: f.line, detail: `<${f.tag}> ${f.attr}="${f.value}" doesn't exist`, message: `<${f.tag}> has no ${f.attr}="${f.value}".${allowed}` };
+  });
+}
+
+/**
+ * Rewrites each JavaScript template expression (lit's `variant=${v}`) as a
+ * Nunjucks-style `{{ }}`, keeping its line breaks so line numbers hold.
+ * checkUsage skips a value only known at run time, but it learned to read
+ * `${` as one only after the bridge's 0.4.0; before that it reported the
+ * expression as a value the component doesn't have. Every bridge release from
+ * lint's floor on already skips `{{ }}`, so lint gives the same answer on all
+ * of them (scripts/test-peer-floors.mjs runs lint's tests against the floor).
+ */
+export const withoutTemplateExpressions = (text) =>
+  text.replace(/\$\{[^}]*\}/g, (expression) => `{{${expression.slice(2, -1).replace(/[^\n]/g, '')}}}`);
+
+// ---- React -----------------------------------------------------------------
+
+// Where a React component for a Web Awesome element can be imported from:
+// Campo's package (`@campo-design/react/button`), or Web Awesome's own
+// wrappers, whose types don't know Campo's contracts but whose use is still
+// checked.
+const REACT_MODULE = /import\s+(?:(\w+)\s*,?\s*)?(?:\{([^}]*)\})?\s*from\s*['"](@campo-design\/react|@awesome\.me\/webawesome\/dist\/react)\/([a-z0-9-]+)(?:\/index\.js)?['"]/g;
+
+/**
+ * The React components a file imports for Web Awesome elements, as a Map of
+ * the local name to its element: `import { WaButton } from
+ * '@campo-design/react/button'` gives WaButton → wa-button. Each module has
+ * one component, so any name imported from it (a default import, a renamed
+ * one) stands for its element. A namespace import (`* as C`) isn't followed.
+ */
+export function reactTags(text) {
+  const tags = new Map();
+  for (const m of text.matchAll(REACT_MODULE)) {
+    const tag = `wa-${m[4]}`;
+    if (m[1]) tags.set(m[1], tag);
+    for (const spec of (m[2] ?? '').split(',')) {
+      const local = spec.replace(/^\s*type\s+/, '').split(/\s+as\s+/).pop().trim();
+      if (/^[A-Z]\w*$/.test(local)) tags.set(local, tag);
+    }
+  }
+  return tags;
+}
+
+/**
+ * JSX that uses React components for Web Awesome elements, rewritten as the
+ * elements: `<WaButton variant="brand">` becomes `<wa-button
+ * variant="brand">`, so every check that reads elements (contract gaps,
+ * icon names) reads React too. Only opening tags change, and never a line
+ * break, so line numbers stay right.
+ */
+export function reactAsElements(text, tags = reactTags(text)) {
+  if (!tags.size) return text;
+  const names = [...tags.keys()].sort((a, b) => b.length - a.length).join('|');
+  return text.replace(new RegExp(`<(${names})(?=[\\s/>])`, 'g'), (_, name) => `<${tags.get(name)}`);
+}
+
+// ---- Setup -----------------------------------------------------------------
+
+/** Web Awesome's own stylesheet: Campo's CSS styles native elements instead. */
+export const WEBAWESOME_STYLESHEET = /webawesome\/dist\/styles\/webawesome\.css/;
+
+/** Web Awesome's autoloader, or its root entry, which starts it. Campo imports each component. */
+export const AUTOLOADER = /webawesome\.loader(?:\.js)?|@awesome\.me\/webawesome\/dist\/webawesome\.js|^@awesome\.me\/webawesome$/;
+
+/** Web Awesome's palette and brand classes: Campo decides color. */
+export const PALETTE_CLASS = /(?<![\w-])wa-(?:palette|brand)-[a-z0-9-]+/g;

package/src/eslint/index.js

@@ -0,0 +1,354 @@
+// Campo's ESLint plugin, for the JavaScript, JSX and templates of a product
+// built with Campo. In a flat config:
+//
+//   import campo from '@campo-design/lint/eslint';
+//   export default [campo.configs.recommended];
+//
+// JavaScript carries Campo's rules in its strings: CSS in template literals
+// and style objects, markup in lit's html`` or innerHTML, import paths. So
+// most rules read string literals and template text, and JSX where it's
+// parsed. They're the same rules Campo's Stylelint config applies to CSS,
+// plus the ones only script can break (imports, icon names, component
+// attributes). Each is described in ../../README.md.
+import {
+  AUTOLOADER,
+  DESIGN_PROPERTY,
+  PALETTE_CLASS,
+  WEBAWESOME_STYLESHEET,
+  classify,
+  contractFindings,
+  cssProperty,
+  iconNames,
+  isPhosphorIcon,
+  reactAsElements,
+  reactTags,
+  styleNumber,
+  tierProblem,
+} from '../core.js';
+
+const docs = (rule, description) => ({
+  description,
+  url: `https://github.com/jlitchfield/campo/blob/main/packages/lint/README.md#campo${rule}`,
+});
+
+// ---- Reading strings ---------------------------------------------------------
+
+/** A string literal's or template element's text, or null for anything else. */
+function textOf(node) {
+  if (node.type === 'Literal' && typeof node.value === 'string') return node.value;
+  if (node.type === 'TemplateElement') return node.value.cooked ?? node.value.raw;
+  if (node.type === 'JSXText') return node.value;
+  return null;
+}
+
+/**
+ * Calls `check(text, node, at)` for every string, template part and JSX text
+ * in a file. `at(index)` turns an offset in the text into a location to report.
+ */
+function eachText(context, check) {
+  const source = context.sourceCode;
+  const visit = (node) => {
+    const text = textOf(node);
+    if (text === null) return;
+    // Skip the opening quote or backtick so offsets land on the text.
+    const start = node.range[0] + (node.type === 'JSXText' ? 0 : 1);
+    const at = (index) => {
+      const loc = source.getLocFromIndex(Math.min(start + index, node.range[1]));
+      return { start: loc, end: loc };
+    };
+    check(text, node, at);
+  };
+  return { Literal: visit, TemplateElement: visit, JSXText: visit };
+}
+
+/** A rule that reports every match of `pattern` in a file's strings. */
+const textRule = ({ name, description, pattern, message }) => ({
+  meta: { type: 'problem', docs: docs(name, description), schema: [], messages: { rejected: message } },
+  create: (context) =>
+    eachText(context, (text, node, at) => {
+      const re = new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`);
+      for (const m of text.matchAll(re)) context.report({ node, loc: at(m.index), messageId: 'rejected', data: { match: m[0] } });
+    }),
+});
+
+// ---- Rules -------------------------------------------------------------------
+
+const semanticTokens = {
+  meta: {
+    type: 'problem',
+    docs: docs('semantic-tokens', 'A var(--campo-*) must be a semantic token: not a primitive, not a name Campo does not define.'),
+    schema: [],
+    messages: { rejected: '{{problem}}' },
+  },
+  create: (context) =>
+    eachText(context, (text, node, at) => {
+      for (const m of text.matchAll(/var\(\s*(--campo-[a-z0-9-]+)/g)) {
+        const problem = tierProblem(m[1]);
+        if (problem) context.report({ node, loc: at(m.index), messageId: 'rejected', data: { problem } });
+      }
+    }),
+};
+
+const LOOKS_LIKE_CSS = /(?<![\w-])[a-z][a-z-]*\s*:\s*[^;{}]+;|style=["']/;
+
+/** Raw design values in CSS written in a template literal or string: `gap: 16px`. */
+function rawInCss(text) {
+  const found = [];
+  const css = text.replace(/\/\*[\s\S]*?\*\//g, (c) => ' '.repeat(c.length));
+  for (const m of css.matchAll(/(?<![\w-])([a-z][a-z-]*)\s*:\s*([^;{}`]+)/g)) {
+    const [, property, value] = m;
+    if (DESIGN_PROPERTY.test(property) && classify(property, value.trim()) === 'raw') found.push({ index: m.index, property, value: value.trim() });
+  }
+  return found;
+}
+
+const noRawValues = {
+  meta: {
+    type: 'problem',
+    docs: docs('no-raw-values', 'Design values in style objects and CSS-in-JS come from Campo tokens, not raw colors, lengths or durations.'),
+    schema: [],
+    messages: {
+      rejected: 'Use a Campo token for {{property}}, not "{{value}}". If none fits, that\'s a token for Campo to add.',
+    },
+  },
+  create(context) {
+    const report = (node, property, value, loc) => context.report({ node, loc, messageId: 'rejected', data: { property, value } });
+
+    /** A style object's properties: { paddingBlock: 8, color: '#333' }. */
+    const checkStyleObject = (object) => {
+      for (const prop of object.properties) {
+        if (prop.type !== 'Property' || prop.computed) continue;
+        const key = prop.key.type === 'Identifier' ? prop.key.name : String(prop.key.value);
+        const property = cssProperty(key);
+        if (property.startsWith('--') || !DESIGN_PROPERTY.test(property)) continue;
+        const { value } = prop;
+        let css = null;
+        if (value.type === 'Literal' && typeof value.value === 'number') css = styleNumber(property, value.value);
+        else if (value.type === 'Literal' && typeof value.value === 'string') css = value.value;
+        else if (value.type === 'TemplateLiteral' && value.expressions.length === 0) css = value.quasis[0].value.cooked;
+        if (css !== null && classify(property, css) === 'raw') report(value, property, css);
+      }
+    };
+
+    return {
+      // JSX: style={{ ... }}
+      JSXAttribute(node) {
+        if (node.name.name !== 'style' || node.value?.type !== 'JSXExpressionContainer') return;
+        if (node.value.expression.type === 'ObjectExpression') checkStyleObject(node.value.expression);
+      },
+      // Object.assign(el.style, { ... }) and el.style.gap = '16px'
+      CallExpression(node) {
+        const { callee, arguments: args } = node;
+        const isAssign = callee.type === 'MemberExpression' && callee.object.name === 'Object' && callee.property.name === 'assign';
+        const target = args[0];
+        const isStyle = target?.type === 'MemberExpression' && target.property.name === 'style';
+        if (isAssign && isStyle && args[1]?.type === 'ObjectExpression') checkStyleObject(args[1]);
+      },
+      AssignmentExpression(node) {
+        const { left, right } = node;
+        if (left.type !== 'MemberExpression' || left.object.type !== 'MemberExpression' || left.object.property.name !== 'style') return;
+        if (left.computed || right.type !== 'Literal') return;
+        const property = cssProperty(left.property.name);
+        const css = typeof right.value === 'number' ? styleNumber(property, right.value) : right.value;
+        if (DESIGN_PROPERTY.test(property) && typeof css === 'string' && classify(property, css) === 'raw') report(right, property, css);
+      },
+      // CSS in a template literal or string: css`...`, <style>${...}</style>, innerHTML.
+      ...eachText(context, (text, node, at) => {
+        // Only text that holds a whole declaration (`gap: 16px;`) or an inline
+        // style, so an ordinary string such as 'Time: 5s' isn't read as CSS.
+        if (!LOOKS_LIKE_CSS.test(text)) return;
+        for (const { index, property, value } of rawInCss(text)) report(node, property, value, at(index));
+      }),
+    };
+  },
+};
+
+const noImportant = textRule({
+  name: 'no-important',
+  description: 'No !important in CSS written in script: layer order is what lets product CSS win.',
+  pattern: /!important\b/,
+  message: "Don't use !important: Campo's CSS is in layers, so product CSS already wins without it.",
+});
+
+const noWaOverride = {
+  meta: {
+    type: 'problem',
+    docs: docs('no-wa-override', 'Never set a --wa-* token: Campo\'s bridge maps every one to a Campo token.'),
+    schema: [],
+    messages: {
+      rejected:
+        "Don't set {{name}}: 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.",
+    },
+  },
+  create(context) {
+    const report = (node, name, loc) => context.report({ node, loc, messageId: 'rejected', data: { name } });
+    return {
+      // CSS in strings and templates: `--wa-color-brand: red;`
+      ...eachText(context, (text, node, at) => {
+        for (const m of text.matchAll(/(--wa-[a-z0-9-]+)\s*:/g)) report(node, m[1], at(m.index));
+      }),
+      // Style objects: { '--wa-color-brand': 'red' }
+      Property(node) {
+        const key = node.key.type === 'Literal' ? node.key.value : null;
+        if (typeof key === 'string' && key.startsWith('--wa-')) report(node.key, key);
+      },
+      // el.style.setProperty('--wa-color-brand', 'red')
+      CallExpression(node) {
+        const [first] = node.arguments;
+        if (node.callee.type === 'MemberExpression' && node.callee.property.name === 'setProperty' && first?.type === 'Literal' && /^--wa-/.test(first.value)) {
+          report(first, first.value);
+        }
+      },
+    };
+  },
+};
+
+const noColorSchemeQuery = textRule({
+  name: 'no-color-scheme-query',
+  description: "Don't handle dark mode in product code: Campo's themes repoint the semantic tokens.",
+  pattern: /prefers-color-scheme/,
+  message:
+    "Don't handle dark mode yourself: Campo's themes repoint the semantic tokens, so a screen built from them is right in both. No media queries or theme checks in script.",
+});
+
+const phosphorIcons = {
+  meta: {
+    type: 'problem',
+    docs: docs('phosphor-icons', '<wa-icon name> takes a Phosphor name. A Font Awesome name draws nothing, with no error.'),
+    schema: [],
+    messages: {
+      rejected:
+        '"{{name}}" isn\'t a Phosphor icon, so <wa-icon> draws nothing. Campo uses Phosphor names (check-circle, x-circle, warning, info), not Font Awesome\'s.',
+    },
+  },
+  create(context) {
+    const report = (node, name, loc) => {
+      if (isPhosphorIcon(name) === false) context.report({ node, loc, messageId: 'rejected', data: { name } });
+    };
+    // React components for <wa-icon>: WaIcon from @campo-design/react/icon, under any name.
+    let tags = new Map();
+    return {
+      Program() {
+        tags = reactTags(context.sourceCode.text);
+      },
+      // Markup in strings and templates.
+      ...eachText(context, (text, node, at) => {
+        for (const { name, index } of iconNames(text)) report(node, name, at(index));
+      }),
+      // JSX: <wa-icon name="…" />, or <WaIcon name="…" /> from @campo-design/react
+      JSXOpeningElement(node) {
+        if (node.name.type !== 'JSXIdentifier') return;
+        if (node.name.name !== 'wa-icon' && tags.get(node.name.name) !== 'wa-icon') return;
+        const attr = node.attributes.find((a) => a.type === 'JSXAttribute' && a.name.name === 'name');
+        if (attr?.value?.type === 'Literal' && typeof attr.value.value === 'string') report(attr.value, attr.value.value);
+      },
+    };
+  },
+};
+
+const contractGaps = {
+  meta: {
+    type: 'problem',
+    docs: docs('contract-gaps', "A Web Awesome component used with a combination its Campo contract lists as a gap, or a value it doesn't have."),
+    schema: [],
+    messages: { rejected: '{{message}}' },
+  },
+  create(context) {
+    return {
+      // The contract check reads markup as text, in HTML strings, templates and
+      // JSX alike. React components from @campo-design/react (or Web Awesome's
+      // own wrappers) are read as the elements they render, so
+      // <WaButton variant="danger" appearance="accent"> is checked like
+      // <wa-button …>: the same check as the package's types, for code
+      // TypeScript doesn't check (plain JavaScript, or a cast).
+      'Program:exit'(node) {
+        const source = context.sourceCode.text;
+        const tags = reactTags(source);
+        const text = reactAsElements(source, tags);
+        if (!/<wa-/.test(text)) return;
+        for (const f of contractFindings(text)) {
+          // Report at the tag as written: <wa-button>, or <WaButton> in React.
+          const line = context.sourceCode.lines[f.line - 1] ?? '';
+          const names = [f.tag, ...[...tags].filter(([, tag]) => tag === f.tag).map(([name]) => name)];
+          let column = -1;
+          let written = f.tag;
+          for (const name of names) {
+            const index = line.search(new RegExp(`<${name}(?=[\\s/>]|$)`));
+            if (index >= 0 && (column < 0 || index < column)) [column, written] = [index, name];
+          }
+          column = Math.max(0, column);
+          const message = written === f.tag ? f.message : f.message.replace(`<${f.tag}>`, `<${written}> (<${f.tag}>)`);
+          context.report({ node, loc: { start: { line: f.line, column }, end: { line: f.line, column: column + written.length + 1 } }, messageId: 'rejected', data: { message } });
+        }
+      },
+    };
+  },
+};
+
+const noWebawesomeStylesheet = textRule({
+  name: 'no-webawesome-stylesheet',
+  description: "Don't import Web Awesome's webawesome.css: Campo's CSS styles native elements.",
+  pattern: WEBAWESOME_STYLESHEET,
+  message: "Don't import Web Awesome's webawesome.css: import @campo-design/webawesome/theme.css, and @campo-design/css for native elements.",
+});
+
+const noAutoloader = {
+  meta: {
+    type: 'problem',
+    docs: docs('no-autoloader', "Import each Web Awesome component; don't use the autoloader or the package's root entry, which starts it."),
+    schema: [],
+    messages: {
+      rejected:
+        'Import each component you use (@awesome.me/webawesome/dist/components/<name>/<name>.js), not the autoloader: Campo checks what an app imports.',
+    },
+  },
+  create(context) {
+    const check = (source) => {
+      if (source?.type === 'Literal' && typeof source.value === 'string' && AUTOLOADER.test(source.value)) {
+        context.report({ node: source, messageId: 'rejected' });
+      }
+    };
+    return {
+      ImportDeclaration: (node) => check(node.source),
+      ImportExpression: (node) => check(node.source),
+      ExportAllDeclaration: (node) => check(node.source),
+      ExportNamedDeclaration: (node) => check(node.source),
+    };
+  },
+};
+
+const noPaletteClass = textRule({
+  name: 'no-palette-class',
+  description: "No wa-palette-* or wa-brand-* classes: Campo decides color.",
+  pattern: PALETTE_CLASS,
+  message: "Don't use {{match}}: Campo decides color through its tokens. Keep <html class=\"wa-theme-default campo-wa\"> only.",
+});
+
+// ---- The plugin ----------------------------------------------------------------
+
+const rules = {
+  'semantic-tokens': semanticTokens,
+  'no-raw-values': noRawValues,
+  'no-important': noImportant,
+  'no-wa-override': noWaOverride,
+  'no-color-scheme-query': noColorSchemeQuery,
+  'phosphor-icons': phosphorIcons,
+  'contract-gaps': contractGaps,
+  'no-webawesome-stylesheet': noWebawesomeStylesheet,
+  'no-autoloader': noAutoloader,
+  'no-palette-class': noPaletteClass,
+};
+
+const plugin = {
+  meta: { name: '@campo-design/lint', namespace: 'campo' },
+  rules,
+  configs: {},
+};
+
+plugin.configs.recommended = {
+  name: '@campo-design/lint/recommended',
+  plugins: { campo: plugin },
+  rules: Object.fromEntries(Object.keys(rules).map((name) => [`campo/${name}`, 'error'])),
+};
+
+export default plugin;