@campo-design/lint 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joshua Litchfield
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,295 @@
-# Temporary Holding Version
+# @campo-design/lint
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Campo's rules, as lint, for products built with Campo: a Stylelint config for
+CSS, and an ESLint plugin for JavaScript, JSX and templates.
+
+Campo's rules only hold where something checks them. Inside the Campo repo,
+`pnpm check` and `pnpm lint` do. A product that installs Campo's packages
+used to get the rules as documentation, with nothing checking them. This
+package moves the checks to where product code is written: the editor, a
+pre-commit hook, CI, and an agent's own session.
+
+It holds no list of tokens, icons or components of its own. It reads them
+from the Campo packages the product has installed (they're peer
+dependencies), so a product's lint always matches its Campo version: a token
+added in the next release is allowed as soon as the product upgrades, and one
+that's removed fails.
+
+## Install
+
+```sh
+npm install --save-dev @campo-design/lint stylelint eslint
+```
+
+`@campo-design/tokens`, `@campo-design/icons`, `@campo-design/webawesome` and
+`@awesome.me/webawesome` are peer dependencies: a product building with Campo
+has them already. Install only the linter you use; both are optional peers.
+It needs `@campo-design/tokens` and `@campo-design/webawesome` 0.3.0 or
+later: the contract check (`checkUsage`) and the manifest's `useInstead`,
+which names the token to use instead of a primitive, first shipped there.
+
+Tested with Stylelint 17 and 18, and ESLint 9 and 10 (flat config), in a
+product installed from the published packages. The peer ranges allow
+Stylelint 16 and later; versions outside the tested ones may work, but
+nothing has checked them.
+
+## Stylelint
+
+```js
+// stylelint.config.js
+export default {
+  extends: ['stylelint-config-recommended', '@campo-design/lint/stylelint'],
+};
+```
+
+Put `@campo-design/lint/stylelint` last in `extends`. A later config
+overrides an earlier one rule by rule, so a config after Campo's could turn a
+Campo rule off or loosen it without anyone noticing. Last, Campo's rules win;
+a deliberate exception goes in your own `rules` or an `overrides` entry,
+where it shows.
+
+The config holds Campo's rules only. `stylelint-config-recommended` adds the
+bug-catching ones (invalid properties, unknown units); it's the product's
+choice. To lint the `<style>` blocks and `style=""` attributes of HTML pages
+too, add [`postcss-html`](https://github.com/ota-meshi/postcss-html):
+
+```js
+overrides: [{ files: ['**/*.html'], customSyntax: 'postcss-html' }],
+```
+
+What the config turns on:
+
+| Rule | Fails on |
+| --- | --- |
+| [`campo/semantic-tokens`](#camposemantic-tokens) | `var(--campo-color-neutral-900)`, a primitive, or `var(--campo-spacing-gap-medium)`, a token that doesn't exist |
+| `color-no-hex`, `color-named`, `function-disallowed-list` | `#1a1a1a`, `white`, `oklch(…)` |
+| `declaration-property-unit-disallowed-list` | `padding: 16px`, `transition-duration: 200ms`, for every property a token family exists for |
+| [`campo/no-raw-through-custom-property`](#campono-raw-through-custom-property) | `--gap: 16px; gap: var(--gap)` |
+| `declaration-property-value-disallowed-list` | `font-weight: 600` |
+| `declaration-no-important` | `!important` |
+| [`campo/no-wa-override`](#campono-wa-override) | `--wa-color-brand-fill-loud: …` |
+| [`campo/no-color-scheme-query`](#campono-color-scheme-query) | `@media (prefers-color-scheme: dark)` |
+
+It also requires a reason on every `stylelint-disable`, after `--`:
+`/* stylelint-disable-next-line color-no-hex -- A specimen of the raw value. */`.
+
+What stays allowed on purpose: layout values (`max-width: 65ch`, grid
+templates, breakpoints), `em` values (they scale with the text), `0`, `%`,
+keywords (`transparent`, `currentColor`, `inherit`), reading a `--wa-*` token,
+and a local custom property for a size two rules share.
+
+## ESLint
+
+```js
+// eslint.config.js
+import campo from '@campo-design/lint/eslint';
+
+export default [
+  { files: ['**/*.{js,jsx}'], ...campo.configs.recommended },
+];
+```
+
+Put Campo's entry after the others, for the same reason as in Stylelint: in
+a flat config, a later entry overrides an earlier one for the files both
+match, so Campo's rules stay on unless you turn one off where it shows.
+
+JavaScript holds Campo's rules in its strings: CSS in template literals and
+style objects, markup in lit's `html` templates, JSX or `innerHTML`, and import
+paths. The rules read those. For JSX, turn it on in the parser
+(`languageOptions.parserOptions.ecmaFeatures.jsx`); for TypeScript, use
+[typescript-eslint](https://typescript-eslint.io)'s parser. The rules are the
+same.
+
+| Rule | Fails on |
+| --- | --- |
+| [`campo/semantic-tokens`](#camposemantic-tokens) | A primitive or an invented `--campo-*` token in a string, template or style object |
+| [`campo/no-raw-values`](#campono-raw-values) | `style={{ padding: 8 }}`, `el.style.gap = '16px'`, ``css`.x { color: #333; }` `` |
+| [`campo/no-important`](#campono-important) | `!important` in CSS written in script |
+| [`campo/no-wa-override`](#campono-wa-override) | `setProperty('--wa-…')`, `{ '--wa-…': … }`, `--wa-…:` in a template |
+| [`campo/no-color-scheme-query`](#campono-color-scheme-query) | `matchMedia('(prefers-color-scheme: dark)')` |
+| [`campo/phosphor-icons`](#campophosphor-icons) | `<wa-icon name="circle-check">` or `<WaIcon name="circle-check">`, a Font Awesome name |
+| [`campo/contract-gaps`](#campocontract-gaps) | `<wa-callout variant="info">`, or a combination the contract lists as a gap, on `<wa-*>` or on React's `<WaButton>` |
+| [`campo/no-webawesome-stylesheet`](#campono-webawesome-stylesheet) | `import '@awesome.me/webawesome/dist/styles/webawesome.css'` |
+| [`campo/no-autoloader`](#campono-autoloader) | `import '@awesome.me/webawesome'` or the autoloader |
+| [`campo/no-palette-class`](#campono-palette-class) | `wa-palette-*` and `wa-brand-*` classes |
+
+## The rules
+
+Each rule is a mistake that renders fine today and breaks at the next theme
+change or redesign. `AGENTS.md`'s *Building with Campo* explains each one,
+with its reason.
+
+### `campo/semantic-tokens`
+
+Stylelint and ESLint. A `var(--campo-*)` must be a semantic token. A
+primitive reaches past the tier, so a theme or redesign doesn't reach it; the
+message names the semantic tokens that point at it, so you can pick by role.
+A name Campo doesn't define looks right and resolves to nothing: check it in
+`@campo-design/tokens/manifest.json`.
+
+### `campo/no-raw-through-custom-property`
+
+Stylelint. The unit rule stops `gap: 16px` but can't see
+`--gap: 16px; gap: var(--gap)`, because a custom property has no type. This
+rule follows a local custom property declared in the same file to where it's
+used, and reports a raw unit that lands in a property a token owns. A local
+custom property for a size is fine where it lands in `inline-size` or `top`.
+
+### `campo/no-raw-values`
+
+ESLint. Raw colors, `px`/`rem` lengths, `ms`/`s` durations and numeric
+weights in style objects (`style={{ }}`, `Object.assign(el.style, { })`,
+`el.style.x = …`) and in CSS written in a string or template. A bare number
+in a style object counts as `px` where React renders it as one
+(`padding: 8`), not where it's unitless (`lineHeight: 1.5`). A string is only
+read as CSS when it holds a whole declaration (`gap: 16px;`) or an inline
+style, so `'Time: 5s'` isn't flagged.
+
+### `campo/no-important`
+
+ESLint. `!important` in CSS written in script, the counterpart of
+Stylelint's `declaration-no-important`. Campo's CSS is in layers, so product
+CSS wins without it.
+
+### `campo/no-wa-override`
+
+Stylelint and ESLint. Declaring or setting 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. Get as close as the component's variants and
+appearances allow, then name the gap as a Campo token decision. Reading a
+`--wa-*` token is fine.
+
+### `campo/no-color-scheme-query`
+
+Stylelint and ESLint. `prefers-color-scheme`, in a media query or in script.
+Campo's themes repoint the semantic tokens, so a screen built from them is
+right in both; a query adds a second, unchecked version of the theme.
+
+### `campo/phosphor-icons`
+
+ESLint. `<wa-icon name>` takes a [Phosphor](https://phosphoricons.com) name.
+Web Awesome's docs use Font Awesome names, and one of those draws nothing,
+with no error. Common ones that differ: `check-circle` (not `circle-check`),
+`x-circle` (not `circle-xmark`), `warning` (not `triangle-exclamation`),
+`info` (not `circle-info`). In React, the same goes for `<WaIcon name>` from
+`@campo-design/react/icon`, under whatever name it's imported as.
+
+### `campo/contract-gaps`
+
+ESLint. A Web Awesome component used with a combination its Campo contract
+lists as a gap (it renders in stock Web Awesome colours, not Campo's), or a
+value the component doesn't have, such as `variant="info"`. The message says
+what to use instead. A value only known at run time (`variant=${v}`,
+`variant={v}`) is skipped, not guessed, with every bridge release from lint's
+floor on, including those before 0.4.1, whose own check read `${v}` as a
+value. The contracts are in
+`@campo-design/webawesome/contracts`.
+
+In React, a component imported from `@campo-design/react` is read as the
+element it renders: `<WaButton variant="danger" appearance="accent">` is
+checked like `<wa-button variant="danger" appearance="accent">`, and the
+message names it as you wrote it (`<WaButton> (<wa-button>) … is a gap`).
+That's also true under a renamed import (`WaButton as Button`), and for
+components imported from Web Awesome's own React wrappers
+(`@awesome.me/webawesome/dist/react/<name>`). A component of your own that
+happens to be called `WaButton` isn't checked.
+
+`@campo-design/react`'s types already reject a gap in TypeScript. This rule
+is the same check for code the types don't stop: plain JavaScript, a line
+silenced with `// @ts-expect-error` or `// @ts-ignore`, and Web Awesome's
+wrappers. Both read the same contracts, so they can't disagree. A value cast
+inside an expression (`variant={'danger' as any}`) is a run-time value to
+this rule, so it isn't checked.
+
+### `campo/no-webawesome-stylesheet`
+
+ESLint. Web Awesome's `webawesome.css`. Import
+`@campo-design/webawesome/theme.css`, and `@campo-design/css` for native
+elements.
+
+### `campo/no-autoloader`
+
+ESLint. Web Awesome's autoloader, or the package's root entry, which starts
+it. Import each component you use from
+`@awesome.me/webawesome/dist/components/<name>/<name>.js`.
+
+### `campo/no-palette-class`
+
+ESLint. `wa-palette-*` and `wa-brand-*` classes. Campo decides color through
+its tokens; `<html>` takes `wa-theme-default campo-wa` only.
+
+## Setup across a product
+
+```sh
+npx campo-lint setup            # the current folder
+npx campo-lint setup src public # or the folders you name
+npx campo-lint setup --json     # for tools and agents
+```
+
+Campo's setup is spread over a product's files: the theme classes on
+`<html>` in a page, `@campo-design/webawesome/theme.css` in a stylesheet or
+script, `connectColorScheme()` and `registerCampoIcons()` (or, in React,
+`setupCampo()`) in a script, and an import for each Web Awesome component
+used. A linter reads one file at a time, so it can't see a step that's
+missing from all of them. `campo-lint setup` reads them together. It
+reports each problem at its file and line, each missing step with what to
+add, and exits 1 when it finds any, so it can run in CI next to lint:
+
+```
+index.html:3  <wa-icon>  (setupImport)
+    Import it from @awesome.me/webawesome/dist/components/<name>/<name>.js (in React, @campo-design/react/<name>).
+Missing from the product (2 files checked):
+  @campo-design/webawesome/theme.css  (setupThemeCss)
+    Import @campo-design/webawesome/theme.css once, in the product's entry stylesheet or script.
+```
+
+It reads stylesheets, pages, templates and scripts (`.css`, `.scss`,
+`.html`, `.njk`, `.md`, `.mdx`, `.js`, `.jsx`, `.ts`, `.tsx`, `.vue`,
+`.svelte`, `.astro`), skipping `node_modules`, build output (`dist`, `build`,
+`out`, `_site`) and hidden folders. Code shown as text, in `<code>`, `<pre>`
+or a Markdown code block, is skipped, so a page that teaches the setup can
+quote it. A product that uses no Web Awesome has nothing to check.
+
+| Rule | Fails on |
+| --- | --- |
+| `setupThemeClass` | `<html>` without both `wa-theme-default` and `campo-wa` |
+| `setupThemeCss` | `@campo-design/webawesome/theme.css` never imported |
+| `setupColorScheme` | `connectColorScheme()` never called (or `setupCampo()` in React) |
+| `setupIcons` | `registerCampoIcons()` never called (or `setupCampo()` in React) |
+| `setupImport` | a `<wa-*>` element used but never imported |
+| `setupStylesheet` | Web Awesome's `webawesome.css` imported |
+| `setupAutoloader` | the autoloader, or the package's root entry, which starts it |
+| `setupPalette` | a `wa-palette-*` or `wa-brand-*` class |
+| `setupReactImport` | a component from Web Awesome's own React wrappers |
+
+## What it doesn't check
+
+- **Setup, in the editor.** The Stylelint and ESLint rules can't see a step
+  missing from every file; `campo-lint setup` (above) checks that, as a
+  command rather than in the editor.
+- **Picking a token by its role.** `gap.related` against `gap.flow`, or
+  `text.subtle` against `text.disabled`, is judgment. The token
+  `$description`s in the manifest are what to read.
+- **Whether a recipe fits.** Run `npx @campo-design/recipes find "<what
+  you're building>"`.
+
+## Exceptions
+
+When an exception is deliberate, say why at the place it's made:
+`/* stylelint-disable-next-line <rule> -- <reason> */`, or
+`// eslint-disable-next-line campo/<rule> -- <reason>`. If you need the
+exception because Campo has no token or variant for what you're building,
+that's a gap for Campo to decide; check *Not mapped yet* in
+`@campo-design/webawesome`'s README, then raise it.
+
+## In the Campo repo
+
+Campo lints itself with this package: the root `stylelint.config.mjs`
+extends `@campo-design/lint/stylelint`, and `eslint.config.mjs` applies the
+recommended ESLint config to the docs' and site's browser scripts. Campo's
+scoring (`scripts/token-score.mjs`, behind `pnpm metrics`, the bench grader
+and the docs and site check) reads the same definitions from
+`@campo-design/lint/core`. So a rule changes in one place, `src/core.js`, and
+means the same thing in a product's lint, Campo's own checks and the bench.
+
+Tests: `pnpm --filter @campo-design/lint test`.

package/bin/campo-lint.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// campo-lint: checks for a whole product, beside the Stylelint config and
+// ESLint plugin, which read one file at a time.
+//
+//   npx campo-lint setup [folder…]   Campo's fixed setup across the product
+//   npx campo-lint setup --json      the same, as JSON
+//
+// It exits 1 when it finds a problem, so it can gate CI.
+import { readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { SETUP_FIXES, setupFindings } from '../src/setup.js';
+
+// Files Campo's setup can appear in: stylesheets, pages, templates, scripts.
+const EXTENSIONS = /\.(css|scss|html|njk|md|mdx|js|mjs|cjs|jsx|ts|tsx|vue|svelte|astro)$/;
+// Dependencies and build output: not the product's own source.
+const SKIP = new Set(['node_modules', 'dist', 'build', 'out', 'coverage', '_site', 'storybook-static']);
+
+const USAGE = `Usage: campo-lint setup [folder…] [--json]
+
+Checks Campo's fixed setup across a product's files: the theme classes on
+<html>, @campo-design/webawesome/theme.css, connectColorScheme() and
+registerCampoIcons() (or setupCampo() in React), an import for each Web
+Awesome component used, and none of webawesome.css, the autoloader, palette
+classes or Web Awesome's own React wrappers. Folders default to the current
+one; node_modules, build output and hidden folders are skipped.`;
+
+/** Every source file under the given paths. */
+export function productFiles(paths) {
+  const walk = (path) => {
+    if (!statSync(path).isDirectory()) return EXTENSIONS.test(path) ? [path] : [];
+    return readdirSync(path)
+      .filter((name) => !name.startsWith('.') && !SKIP.has(name))
+      .flatMap((name) => walk(join(path, name)));
+  };
+  return paths.flatMap((p) => walk(resolve(p)));
+}
+
+/** The report a person reads: problems in files first, then missing steps. */
+export function formatReport(findings, fileCount, base = process.cwd()) {
+  if (!findings.length) return `No setup problems (${fileCount} files checked).`;
+  const lines = [];
+  const inFiles = findings.filter((f) => f.file);
+  const missing = findings.filter((f) => !f.file);
+  for (const f of inFiles) lines.push(`${relative(base, f.file)}:${f.line}  ${f.detail}  (${f.rule})\n    ${SETUP_FIXES[f.rule]}`);
+  if (missing.length) {
+    lines.push(`Missing from the product (${fileCount} files checked):`);
+    for (const f of missing) lines.push(`  ${f.detail}  (${f.rule})\n    ${SETUP_FIXES[f.rule]}`);
+  }
+  lines.push(`\n${findings.length} setup problem${findings.length === 1 ? '' : 's'}. The setup is under "Use" in @campo-design/webawesome's README.`);
+  return lines.join('\n');
+}
+
+// Run as a command, directly or through npx's link in node_modules/.bin;
+// not when a test imports productFiles or formatReport.
+const invoked = process.argv[1] && pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url;
+const [command, ...rest] = process.argv.slice(2);
+if (invoked) {
+  if (command !== 'setup' || rest.includes('--help')) {
+    console.log(USAGE);
+    process.exit(command === 'setup' || command === '--help' || !command ? 0 : 2);
+  }
+  const json = rest.includes('--json');
+  const folders = rest.filter((a) => !a.startsWith('--'));
+  const files = productFiles(folders.length ? folders : ['.']);
+  const findings = setupFindings(files.map((file) => ({ file, text: readFileSync(file, 'utf8') })));
+  if (json) {
+    const base = process.cwd();
+    console.log(JSON.stringify({ files: files.length, findings: findings.map((f) => ({ ...f, file: f.file && relative(base, f.file), fix: SETUP_FIXES[f.rule] })) }, null, 2));
+  } else {
+    console.log(formatReport(findings, files.length));
+  }
+  process.exit(findings.length ? 1 : 0);
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@campo-design/lint",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Campo's lint rules for products: a Stylelint config and an ESLint plugin that fail on raw values, primitives, invented tokens, Web Awesome overrides, hand-rolled dark mode, non-Phosphor icons and contract gaps.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "campo-lint": "./bin/campo-lint.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "exports": {
+    "./stylelint": "./src/stylelint/index.js",
+    "./stylelint/plugin": "./src/stylelint/plugin.js",
+    "./eslint": "./src/eslint/index.js",
+    "./core": "./src/core.js",
+    "./setup": "./src/setup.js"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "@awesome.me/webawesome": "^3.14.0",
+    "@campo-design/icons": ">=0.1.0 <1.0.0",
+    "@campo-design/tokens": ">=0.3.0 <1.0.0",
+    "@campo-design/webawesome": ">=0.3.0 <1.0.0",
+    "eslint": ">=9.0.0",
+    "stylelint": ">=16.0.0"
+  },
+  "peerDependenciesMeta": {
+    "eslint": {
+      "optional": true
+    },
+    "stylelint": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@awesome.me/webawesome": "3.14.0",
+    "eslint": "^10.14.0",
+    "stylelint": "^17.16.0",
+    "@campo-design/icons": "^0.1.0",
+    "@campo-design/tokens": "^0.3.1",
+    "@campo-design/webawesome": "^0.4.1"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  }
 }