eslint-plugin-kerfjs 5.0.0-beta.29 → 5.0.0-beta.30

package/README.md

@@ -55,7 +55,7 @@ Applications using the UI catalog can select one of two additive flat configs:
 export default [
   // parser/files configuration as above
   kerfjs.configs['recommended-ui'], // preferences and wiring are warnings
-  // or kerfjs.configs['strict-ui']  // all four UI contracts are errors
+  // or kerfjs.configs['strict-ui']  // all UI contracts are errors
 ];
 ```
 
@@ -77,7 +77,12 @@ settings: {
 
 For deterministic generated configs, the same settings accept parsed `catalog`, `selectionCatalog`, and `profile` objects. File-based precedence is package defaults, then workspace profile, then root-to-leaf directory profiles. The rules load `application-ui-profile-sync.cjs` from the installed `@kerfjs/ui` package by default because ESLint rule creation is synchronous; `profileContractPath` is only needed when artifacts are vendored. Every raw layer is schema- and catalog-reference-validated before merge, so a child cannot hide malformed or stale parent policy. Exceptions use exact `KUI-L*` diagnostic ids and repository-relative file or directory targets.
 
-`KUI-L090` is reserved for catalog/profile loading and configuration failures; it does not collide with the static analyzer's `KUI-L001`–`KUI-L009` findings. The supported-ESLint matrix installs real packed `eslint-plugin-kerfjs` and `@kerfjs/ui` tarballs in a downstream flat-config fixture, ensuring these defaults resolve from the consumer rather than this repository's source tree.
+`ui-css-values` consumes each catalog entry's property-specific grammar and
+emits `KUI-L013`–`KUI-L017` with a preferred shorthand or helper. It covers JSX,
+direct component calls, nested catalog paths, and explicitly configured
+third-party catalogs; dynamic values remain governed by TypeScript.
+
+`KUI-L090` is reserved for catalog/profile loading and configuration failures. The supported-ESLint matrix installs real packed `eslint-plugin-kerfjs` and `@kerfjs/ui` tarballs in a downstream flat-config fixture, ensuring these defaults resolve from the consumer rather than this repository's source tree.
 
 ## Legacy `.eslintrc` configs are not supported
 
@@ -99,6 +104,7 @@ Use flat config (`eslint.config.js`), shown above. The `legacy-recommended` expo
 | [`ai-assistant-configs`](docs/rules/ai-assistant-configs.md)                     | — (project hygiene)                                  | `warn`                 |
 | [`ui-public-boundaries`](docs/rules/ui-public-boundaries.md)                     | — (cataloged CSS boundaries)                         | `error`                |
 | [`ui-composition`](docs/rules/ui-composition.md)                                 | — (cataloged parents and zones)                      | `error`                |
+| [`ui-css-values`](docs/rules/ui-css-values.md)                                   | — (cataloged property-specific value grammar)        | `error`                |
 | [`ui-preferences`](docs/rules/ui-preferences.md)                                 | — (application component choices)                    | `warn`                 |
 | [`ui-wiring`](docs/rules/ui-wiring.md)                                           | — (required setup and cleanup)                       | `warn`                 |
 

package/docs/rules/ui-composition.md

@@ -1,5 +1,5 @@
 # `ui-composition`
 
-Enforces composition facts published by the versioned UI catalog. `KUI-L201` reports a catalog component under a known, disallowed direct parent. `KUI-L202` reports a statically visible zone child—including an intrinsic or unknown JSX element—that is not one of the zone's cataloged `accepts` entries. `KUI-L203` reports a statically provable zone cardinality violation. Toolbar's `leading`, `center`, and `trailing` validation is therefore derived from its catalog entry rather than a duplicated rule-local allowlist.
+Enforces composition facts published by the versioned UI catalog. `KUI-L201` reports a catalog component under a known, disallowed direct parent. `KUI-L202` reports a statically visible zone child—including an intrinsic or unknown JSX element—that is not one of the zone's cataloged `accepts` entries. `KUI-L203` reports a statically provable zone cardinality violation. A zone participates only when it declares an explicit `jsx.prop` binding, including `children`; the rule never guesses that a zone id is a JSX prop. Toolbar, Pane, TabBar, AppTab, feedback, search, and layout validation is therefore catalog-driven rather than duplicated in rule-local component cases.
 
-The parent check is intentionally conservative: it reports only when both child and direct parent resolve to cataloged imports. The Toolbar zone check understands fragments, arrays, and conditional/logical branches, but expressions whose content cannot be resolved statically remain runtime and accessibility work. Other catalog zone ids are not assumed to be JSX prop names. No autofix is offered because wrapping or moving UI changes structure and behavior.
+The parent check is intentionally conservative: it reports only when both child and direct parent resolve to cataloged imports. Bound zone checks understand aliases, namespace imports, fragments, arrays, and conditional/logical branches, but expressions whose content cannot be resolved statically remain runtime and accessibility work. Accepted concepts that do not identify a catalog entry remain machine-readable guidance while the rule enforces their statically provable cardinality only. No autofix is offered because wrapping or moving UI changes structure and behavior.

package/docs/rules/ui-css-values.md

@@ -0,0 +1,15 @@
+# `ui-css-values`
+
+Checks literal JSX and direct component-function calls against each component's
+cataloged `cssValueProps` contracts. The catalog keeps length, size, flex,
+color, declaration-list, media-query, and numeric-pixel grammars distinct and
+names their accepted helpers, finite shorthands, and raw-value policy.
+
+Stable diagnostics are `KUI-L013` (raw or unknown shorthand), `KUI-L014`
+(wrong property helper), `KUI-L015` (non-standalone expression), `KUI-L016`
+(forbidden declaration list), and review-oriented `KUI-L017` (exceptional
+spacing shorthand). Messages name the preferred shorthand or helper. Dynamic
+values are left to TypeScript rather than guessed.
+
+Third-party component suites can provide the same contracts in a composition
+catalog through `settings.kerfjs.ui.catalog` and its matching selection catalog.

package/index.js

@@ -7,12 +7,13 @@ import preferModuleJsxAugmentation from './lib/rules/prefer-module-jsx-augmentat
 import requireDataKeyInEach from './lib/rules/require-data-key-in-each.js';
 import requireDelegateDisposer from './lib/rules/require-delegate-disposer.js';
 import uiComposition from './lib/rules/ui-composition.js';
+import uiCssValues from './lib/rules/ui-css-values.js';
 import uiPreferences from './lib/rules/ui-preferences.js';
 import uiPublicBoundaries from './lib/rules/ui-public-boundaries.js';
 import uiWiring from './lib/rules/ui-wiring.js';
 
 const plugin = {
-  meta: { name: 'eslint-plugin-kerfjs', version: '5.0.0-beta.29' },
+  meta: { name: 'eslint-plugin-kerfjs', version: '5.0.0-beta.30' },
   rules: {
     'no-inline-jsx-event-handlers': noInlineJsxEventHandlers,
     'no-raw-with-dynamic-arg': noRawWithDynamicArg,
@@ -23,6 +24,7 @@ const plugin = {
     'prefer-attr-selector': preferAttrSelector,
     'ai-assistant-configs': aiAssistantConfigs,
     'ui-composition': uiComposition,
+    'ui-css-values': uiCssValues,
     'ui-preferences': uiPreferences,
     'ui-public-boundaries': uiPublicBoundaries,
     'ui-wiring': uiWiring,
@@ -62,6 +64,7 @@ const recommendedUiRules = {
   ...recommendedRules,
   'kerfjs/ui-public-boundaries': 'error',
   'kerfjs/ui-composition': 'error',
+  'kerfjs/ui-css-values': 'error',
   'kerfjs/ui-preferences': 'warn',
   'kerfjs/ui-wiring': 'warn',
 };

package/lib/rules/ui-composition.js

@@ -94,6 +94,28 @@ function directParentKey(node, registry, contract) {
     : undefined;
 }
 
+function boundZone(openingElement, zone, registry, contract) {
+  const prop = zone.jsx?.prop;
+  if (!prop) return undefined;
+  if (prop === 'children')
+    return {
+      node: openingElement.name,
+      shape: combine(
+        (openingElement.parent?.children ?? []).map((child) =>
+          zoneShape(child, registry, contract),
+        ),
+      ),
+    };
+  const attribute = openingElement.attributes.find(
+    (candidate) =>
+      candidate.type === 'JSXAttribute' && candidate.name.name === prop,
+  );
+  return {
+    node: attribute ?? openingElement.name,
+    shape: zoneShape(attribute?.value, registry, contract),
+  };
+}
+
 export default {
   meta: {
     type: 'problem',
@@ -143,17 +165,10 @@ export default {
               data: { child: key, parents: entry.parents.entries.join(', ') },
             });
         }
-        // Catalog zone ids are not universally JSX prop names. Toolbar's public
-        // API deliberately exposes its three zones as same-named props, so only
-        // that component has a sound static prop-to-zone mapping here.
-        if (entry.id !== 'toolbar') return;
         for (const zone of entry.zones ?? []) {
-          const attribute = node.attributes.find(
-            (candidate) =>
-              candidate.type === 'JSXAttribute' &&
-              candidate.name.name === zone.id,
-          );
-          const shape = zoneShape(attribute?.value, registry, contract);
+          const bound = boundZone(node, zone, registry, contract);
+          if (!bound) continue;
+          const { node: reportNode, shape } = bound;
           const allowed = new Set(
             zone.accepts
               .map((accepted) =>
@@ -167,7 +182,7 @@ export default {
             for (const child of shape.items)
               if (!child.key || !allowed.has(child.key))
                 context.report({
-                  node: attribute ?? node.name,
+                  node: reportNode,
                   messageId: 'zone',
                   data: {
                     component: key,
@@ -182,7 +197,7 @@ export default {
           const tooMany = max !== 'unbounded' && shape.min > max;
           if (tooFew || tooMany)
             context.report({
-              node: attribute ?? node.name,
+              node: reportNode,
               messageId: 'cardinality',
               data: {
                 component: key,

package/lib/rules/ui-css-values.js

@@ -0,0 +1,243 @@
+import {
+  helperCall,
+  importRegistry,
+  isExcepted,
+  jsxKey,
+  loadUiContract,
+  UI_CONTRACT_LOAD_CODE,
+  UI_RULE_SCHEMA,
+} from '../ui-contract.js';
+
+const CODES = {
+  raw: 'KUI-L013',
+  helper: 'KUI-L014',
+  expression: 'KUI-L015',
+  declarations: 'KUI-L016',
+  exceptional: 'KUI-L017',
+};
+
+function propertyName(node) {
+  if (!node || node.computed) return undefined;
+  return node.key?.name ?? node.key?.value;
+}
+
+function objectProperty(object, name) {
+  return object?.properties?.find(
+    (property) =>
+      property.type === 'Property' && propertyName(property) === name,
+  );
+}
+
+function jsxAttribute(opening, name) {
+  return opening.attributes.find(
+    (attribute) =>
+      attribute.type === 'JSXAttribute' && attribute.name.name === name,
+  );
+}
+
+function jsxValue(attribute) {
+  if (!attribute?.value) return undefined;
+  if (attribute.value.type === 'Literal') return attribute.value;
+  if (attribute.value.type === 'JSXExpressionContainer')
+    return attribute.value.expression;
+  return undefined;
+}
+
+function nestedValues(value, tail) {
+  if (!tail) return [value];
+  if (value?.type !== 'ArrayExpression') return [];
+  return value.elements.flatMap((element) => {
+    if (element?.type !== 'ObjectExpression') return [];
+    const property = objectProperty(element, tail);
+    return property ? [property.value] : [];
+  });
+}
+
+function contractValuesFromJsx(opening, path) {
+  const [head, tail] = path.split('[].');
+  return nestedValues(jsxValue(jsxAttribute(opening, head)), tail);
+}
+
+function contractValuesFromCall(call, path) {
+  const options = call.arguments[0];
+  if (options?.type !== 'ObjectExpression') return [];
+  const [head, tail] = path.split('[].');
+  const property = objectProperty(options, head);
+  return property ? nestedValues(property.value, tail) : [];
+}
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Enforce cataloged property-specific CSS value contracts for Kerf UI components.',
+      url: 'https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/docs/rules/ui-css-values.md',
+    },
+    schema: UI_RULE_SCHEMA,
+    messages: {
+      config: `${UI_CONTRACT_LOAD_CODE}: Kerf UI catalog/profile could not be loaded: {{error}}`,
+      raw: '{{code}}: `{{component}}.{{path}}` uses {{grammar}} grammar; replace raw `{{value}}` with {{preferred}}.',
+      helper:
+        '{{code}}: `{{helper}}()` produces the wrong grammar for `{{component}}.{{path}}`; use {{preferred}}.',
+      expression:
+        '{{code}}: `{{helper}}()` is not a standalone CSS value for `{{component}}.{{path}}`; wrap it with an accepted composer such as `calc()`.',
+      declarations:
+        '{{code}}: `{{component}}.{{path}}` is a forbidden declaration-list escape hatch; use `className`, public tokens, or cataloged props.',
+      exceptional:
+        '{{code}}: `{{value}}` is an exceptional shorthand for `{{component}}.{{path}}`; prefer {{preferred}} unless the off-scale choice is deliberate.',
+    },
+  },
+  create(context) {
+    const loaded = loadUiContract(context);
+    const filename = context.filename ?? context.getFilename();
+    let registry;
+
+    const inspect = (node, entry, valuesFor) => {
+      for (const cssContract of entry.cssValueProps ?? []) {
+        const preferred =
+          [
+            ...(cssContract.canonicalShorthands ?? []).map(
+              (item) => `\`${item}\``,
+            ),
+            ...(cssContract.helpers ?? []).map((item) => `\`${item}()`),
+          ].join(' or ') || 'a cataloged component prop';
+        for (const value of valuesFor(cssContract.path)) {
+          if (!value) continue;
+          if (
+            cssContract.grammar === 'declarations' &&
+            cssContract.rawPolicy !== 'allow'
+          ) {
+            if (!isExcepted(loaded, CODES.declarations, filename))
+              context.report({
+                node: value,
+                messageId: 'declarations',
+                data: {
+                  code: CODES.declarations,
+                  component: entry.name,
+                  path: cssContract.path,
+                },
+              });
+            continue;
+          }
+          const literal =
+            value.type === 'Literal' && typeof value.value === 'string'
+              ? value.value
+              : value.type === 'TemplateLiteral' &&
+                  value.expressions.length === 0
+                ? value.quasis[0].value.cooked
+                : undefined;
+          if (literal !== undefined) {
+            if (cssContract.exceptionalShorthands?.includes(literal)) {
+              if (!isExcepted(loaded, CODES.exceptional, filename))
+                context.report({
+                  node: value,
+                  messageId: 'exceptional',
+                  data: {
+                    code: CODES.exceptional,
+                    component: entry.name,
+                    path: cssContract.path,
+                    value: literal,
+                    preferred,
+                  },
+                });
+            } else if (
+              !cssContract.shorthands?.includes(literal) &&
+              cssContract.rawPolicy !== 'allow'
+            ) {
+              const code = CODES.raw;
+              if (!isExcepted(loaded, code, filename))
+                context.report({
+                  node: value,
+                  messageId: 'raw',
+                  data: {
+                    code,
+                    component: entry.name,
+                    path: cssContract.path,
+                    grammar: cssContract.grammar,
+                    value: literal,
+                    preferred,
+                  },
+                });
+            }
+            continue;
+          }
+          if (value.type !== 'CallExpression') continue;
+          const helper = helperCall(value.callee, registry, loaded);
+          if (!helper) continue;
+          if (cssContract.nonStandaloneHelpers?.includes(helper.imported)) {
+            if (!isExcepted(loaded, CODES.expression, filename))
+              context.report({
+                node: value,
+                messageId: 'expression',
+                data: {
+                  code: CODES.expression,
+                  component: entry.name,
+                  path: cssContract.path,
+                  helper: helper.imported,
+                },
+              });
+          } else if (
+            !cssContract.helpers?.includes(helper.imported) &&
+            cssContract.unsafeHelper !== helper.imported
+          ) {
+            if (!isExcepted(loaded, CODES.helper, filename))
+              context.report({
+                node: value,
+                messageId: 'helper',
+                data: {
+                  code: CODES.helper,
+                  component: entry.name,
+                  path: cssContract.path,
+                  helper: helper.imported,
+                  preferred,
+                },
+              });
+          }
+        }
+      }
+    };
+
+    return {
+      Program(node) {
+        if (loaded.error)
+          context.report({
+            node,
+            messageId: 'config',
+            data: { error: loaded.error },
+          });
+        else registry = importRegistry(node, loaded);
+      },
+      JSXOpeningElement(node) {
+        if (!registry) return;
+        const key = jsxKey(node.name, registry, loaded);
+        const entry = loaded.entries.get(key);
+        if (entry)
+          inspect(node, entry, (path) => contractValuesFromJsx(node, path));
+      },
+      CallExpression(node) {
+        if (!registry) return;
+        let key;
+        if (node.callee.type === 'Identifier')
+          key = registry.locals.get(node.callee.name);
+        else if (
+          node.callee.type === 'MemberExpression' &&
+          !node.callee.computed &&
+          node.callee.object.type === 'Identifier' &&
+          node.callee.property.type === 'Identifier'
+        ) {
+          const source = registry.namespaces.get(node.callee.object.name);
+          const exportedKey = loaded.exports.get(node.callee.property.name);
+          if (
+            source === loaded.package ||
+            loaded.imports.get(source) === exportedKey
+          )
+            key = exportedKey;
+        }
+        const entry = loaded.entries.get(key);
+        if (entry)
+          inspect(node, entry, (path) => contractValuesFromCall(node, path));
+      },
+    };
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-kerfjs",
-  "version": "5.0.0-beta.29",
+  "version": "5.0.0-beta.30",
   "description": "ESLint rules that enforce kerf's hard rules — catches AI-shaped bugs at edit time.",
   "type": "module",
   "license": "MIT",