eslint-plugin-kerfjs 5.0.0-beta.18 → 5.0.0-beta.19

package/README.md

@@ -19,6 +19,7 @@ All but one rule are AST-only — no `@typescript-eslint/parser` _service_ depen
 
 ```bash
 npm install --save-dev eslint-plugin-kerfjs
+npm install @kerfjs/ui
 ```
 
 ### Supported ESLint versions
@@ -48,6 +49,36 @@ export default [
 ];
 ```
 
+Applications using the UI catalog can select one of two additive flat configs:
+
+```js
+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
+];
+```
+
+The UI rules resolve the installed `@kerfjs/ui` v1 selection catalog, v2 composition catalog, and application profile defaults. They then merge `.kerf-ui-profile.json` files from the workspace root toward the linted file. Package authors and monorepos can provide explicit artifacts without duplicating their facts:
+
+```js
+settings: {
+  kerfjs: {
+    ui: {
+      workspaceRoot: import.meta.dirname,
+      catalogPath: './vendor/component-catalog-v2.json',
+      selectionCatalogPath: './vendor/component-catalog.json',
+      profileDefaultsPath: './vendor/application-ui-profile.defaults.json',
+      profileContractPath: './vendor/application-ui-profile-sync.cjs',
+    },
+  },
+}
+```
+
+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.
+
 ## Legacy `.eslintrc` configs are not supported
 
 The package is ESM-only. ESLint's `.eslintrc` system loads plugins with `require()`, which cannot load an ESM package, so `extends: ["plugin:kerfjs/legacy-recommended"]` fails with _"couldn't find the config to extend from"_ on ESLint 8 **and** on ESLint 9's legacy mode.
@@ -66,6 +97,10 @@ Use flat config (`eslint.config.js`), shown above. The `legacy-recommended` expo
 | [`prefer-attr-selector`](docs/rules/prefer-attr-selector.md)                     | — (rename-safety nudge for `delegate()` selectors)   | `warn`                 |
 | [`no-raw-with-dynamic-arg`](docs/rules/no-raw-with-dynamic-arg.md)               | — (XSS audit trail)                                  | `warn`                 |
 | [`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-preferences`](docs/rules/ui-preferences.md)                                 | — (application component choices)                    | `warn`                 |
+| [`ui-wiring`](docs/rules/ui-wiring.md)                                           | — (required setup and cleanup)                       | `warn`                 |
 
 The "Hard Rule" column refers to the numbered rules in [`docs/ai/usage-guide.md`](../docs/ai/usage-guide.md) on the main kerf repo. `no-raw-with-dynamic-arg` and `ai-assistant-configs` don't map to numbered Hard Rules — the former creates an audit trail for every dynamic `raw()` call site (potential XSS); the latter checks that the bundled AI-assistant configs are installed and current. See [`docs/12-ai-assistant-configs.md`](../docs/12-ai-assistant-configs.md) on the main kerf repo for the AI-configs design.
 

package/docs/rules/ui-composition.md

@@ -0,0 +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.
+
+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.

package/docs/rules/ui-preferences.md

@@ -0,0 +1,5 @@
+# `ui-preferences`
+
+Reports cataloged components listed in an application UI profile preference's `avoid` set and points to the package-qualified `preferred` component. The stable diagnostic is `KUI-L301`.
+
+`recommended-ui` treats the rule as a warning; `strict-ui` treats it as an error. Use a narrowly targeted `KUI-L301` profile exception when a documented application boundary cannot follow the preference. Component substitutions are not autofixed because their props and interaction contracts can differ.

package/docs/rules/ui-public-boundaries.md

@@ -0,0 +1,7 @@
+# `ui-public-boundaries`
+
+Rejects `kui-*` classes and `--kui-*` custom properties that are not listed in the versioned composition catalog. This keeps application code out of private component anatomy while allowing cataloged styling seams.
+
+Diagnostics are stable: `KUI-L101` identifies a private/unknown class and `KUI-L102` an unknown token. Exact profile exceptions can name either id. The rule deliberately does not rewrite selectors or tokens because there is no generally safe replacement.
+
+The rule reads `@kerfjs/ui/ai/component-catalog-v2.json` by default. See the plugin README for alternate catalog settings used by monorepos and package authors.

package/docs/rules/ui-wiring.md

@@ -0,0 +1,5 @@
+# `ui-wiring`
+
+Checks wiring obligations published by the versioned composition catalog. `KUI-L401` reports a used component whose required helper or side-effect registration import is absent. `KUI-L402` reports a helper call whose disposer is discarded.
+
+Assign, return, or otherwise retain a disposer when the binding has a shorter lifetime than the page. A `void` call is accepted as an explicit page-lifetime choice. The rule derives valid helper sources from each v1 entry's `publicExports` and `wiring[].import` facts, so aliases, root named imports, root namespaces, wiring-subpath named imports, and wiring-subpath namespaces resolve without a second hard-coded export table. It does not attempt flow-sensitive cleanup proof and offers no autofix.

package/index.js

@@ -6,9 +6,13 @@ import preferAttrSelector from './lib/rules/prefer-attr-selector.js';
 import preferModuleJsxAugmentation from './lib/rules/prefer-module-jsx-augmentation.js';
 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 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.18' },
+  meta: { name: 'eslint-plugin-kerfjs', version: '5.0.0-beta.19' },
   rules: {
     'no-inline-jsx-event-handlers': noInlineJsxEventHandlers,
     'no-raw-with-dynamic-arg': noRawWithDynamicArg,
@@ -18,6 +22,10 @@ const plugin = {
     'prefer-module-jsx-augmentation': preferModuleJsxAugmentation,
     'prefer-attr-selector': preferAttrSelector,
     'ai-assistant-configs': aiAssistantConfigs,
+    'ui-composition': uiComposition,
+    'ui-preferences': uiPreferences,
+    'ui-public-boundaries': uiPublicBoundaries,
+    'ui-wiring': uiWiring,
   },
   configs: {},
 };
@@ -50,6 +58,25 @@ plugin.configs.recommended = {
   plugins: { kerfjs: plugin },
   rules: recommendedRules,
 };
+const recommendedUiRules = {
+  ...recommendedRules,
+  'kerfjs/ui-public-boundaries': 'error',
+  'kerfjs/ui-composition': 'error',
+  'kerfjs/ui-preferences': 'warn',
+  'kerfjs/ui-wiring': 'warn',
+};
+plugin.configs['recommended-ui'] = {
+  plugins: { kerfjs: plugin },
+  rules: recommendedUiRules,
+};
+plugin.configs['strict-ui'] = {
+  plugins: { kerfjs: plugin },
+  rules: {
+    ...recommendedUiRules,
+    'kerfjs/ui-preferences': 'error',
+    'kerfjs/ui-wiring': 'error',
+  },
+};
 plugin.configs.all = plugin.configs.recommended;
 
 // Legacy `.eslintrc` config — consumers extend `'plugin:kerfjs/legacy-recommended'`.

package/lib/rules/ui-composition.js

@@ -0,0 +1,198 @@
+import {
+  importRegistry,
+  isExcepted,
+  jsxKey,
+  loadUiContract,
+  UI_CONTRACT_LOAD_CODE,
+  UI_RULE_SCHEMA,
+} from '../ui-contract.js';
+
+const PARENT_CODE = 'KUI-L201';
+const ZONE_CODE = 'KUI-L202';
+const CARDINALITY_CODE = 'KUI-L203';
+
+const emptyShape = () => ({ min: 0, max: 0, items: [] });
+
+function combine(shapes) {
+  return shapes.reduce(
+    (result, shape) => ({
+      min: result.min + shape.min,
+      max: result.max + shape.max,
+      items: [...result.items, ...shape.items],
+    }),
+    emptyShape(),
+  );
+}
+
+function jsxLabel(name) {
+  if (name.type === 'JSXIdentifier') return `<${name.name}>`;
+  if (name.type === 'JSXMemberExpression')
+    return `${jsxLabel(name.object).slice(0, -1)}.${name.property.name}>`;
+  return '<unknown>';
+}
+
+function zoneShape(node, registry, contract) {
+  if (!node || node.type === 'JSXEmptyExpression') return emptyShape();
+  if (node.type === 'JSXElement') {
+    const key = jsxKey(node.openingElement.name, registry, contract);
+    return {
+      min: 1,
+      max: 1,
+      items: [{ key, label: key ?? jsxLabel(node.openingElement.name) }],
+    };
+  }
+  if (node.type === 'JSXFragment')
+    return combine(
+      node.children.map((child) => zoneShape(child, registry, contract)),
+    );
+  if (node.type === 'JSXText')
+    return node.value.trim()
+      ? { min: 1, max: 1, items: [{ label: 'text' }] }
+      : emptyShape();
+  if (node.type === 'JSXExpressionContainer')
+    return zoneShape(node.expression, registry, contract);
+  if (node.type === 'ArrayExpression')
+    return combine(
+      node.elements.map((child) => zoneShape(child, registry, contract)),
+    );
+  if (node.type === 'ConditionalExpression') {
+    const consequent = zoneShape(node.consequent, registry, contract);
+    const alternate = zoneShape(node.alternate, registry, contract);
+    return {
+      min: Math.min(consequent.min, alternate.min),
+      max: Math.max(consequent.max, alternate.max),
+      items: [...consequent.items, ...alternate.items],
+    };
+  }
+  if (node.type === 'LogicalExpression') {
+    const left = zoneShape(node.left, registry, contract);
+    const right = zoneShape(node.right, registry, contract);
+    return node.operator === '&&'
+      ? { min: 0, max: right.max, items: right.items }
+      : {
+          min: Math.min(left.min, right.min),
+          max: Math.max(left.max, right.max),
+          items: [...left.items, ...right.items],
+        };
+  }
+  if (node.type === 'Literal')
+    return node.value === null || typeof node.value === 'boolean'
+      ? emptyShape()
+      : { min: 1, max: 1, items: [{ label: 'text' }] };
+  return { min: 0, max: Number.POSITIVE_INFINITY, items: [] };
+}
+
+function directParentKey(node, registry, contract) {
+  let parent = node.parent?.parent;
+  while (
+    parent &&
+    ['JSXExpressionContainer', 'JSXFragment'].includes(parent.type)
+  )
+    parent = parent.parent;
+  return parent?.type === 'JSXElement'
+    ? { key: jsxKey(parent.openingElement.name, registry, contract) }
+    : undefined;
+}
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Enforce low-false-positive catalog parent and zone contracts.',
+      url: 'https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/docs/rules/ui-composition.md',
+    },
+    schema: UI_RULE_SCHEMA,
+    messages: {
+      config: `${UI_CONTRACT_LOAD_CODE}: Kerf UI catalog/profile could not be loaded: {{error}}`,
+      parent:
+        'KUI-L201: `{{child}}` requires one of these cataloged parents: {{parents}}.',
+      zone: 'KUI-L202: `{{component}}` zone `{{zone}}` does not accept {{child}}; catalog accepts: {{accepts}}.',
+      cardinality:
+        'KUI-L203: `{{component}}` zone `{{zone}}` requires {{cardinality}} direct children; statically found {{count}}.',
+    },
+  },
+  create(context) {
+    const contract = loadUiContract(context);
+    const filename = context.filename ?? context.getFilename();
+    let registry;
+    return {
+      Program(node) {
+        if (contract.error)
+          context.report({
+            node,
+            messageId: 'config',
+            data: { error: contract.error },
+          });
+        else registry = importRegistry(node, contract);
+      },
+      JSXOpeningElement(node) {
+        if (!registry) return;
+        const key = jsxKey(node.name, registry, contract);
+        const entry = contract.entries.get(key);
+        if (!entry) return;
+        if (
+          entry.parents.mode === 'listed' &&
+          !isExcepted(contract, PARENT_CODE, filename)
+        ) {
+          const parent = directParentKey(node, registry, contract);
+          if (parent && !entry.parents.entries.includes(parent.key))
+            context.report({
+              node: node.name,
+              messageId: 'parent',
+              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 allowed = new Set(
+            zone.accepts
+              .map((accepted) =>
+                accepted.includes(':')
+                  ? accepted
+                  : `${entry.package}:${accepted}`,
+              )
+              .filter((accepted) => contract.entries.has(accepted)),
+          );
+          if (allowed.size && !isExcepted(contract, ZONE_CODE, filename))
+            for (const child of shape.items)
+              if (!child.key || !allowed.has(child.key))
+                context.report({
+                  node: attribute ?? node.name,
+                  messageId: 'zone',
+                  data: {
+                    component: key,
+                    zone: zone.id,
+                    child: child.label,
+                    accepts: [...allowed].join(', '),
+                  },
+                });
+          if (isExcepted(contract, CARDINALITY_CODE, filename)) continue;
+          const { min, max } = zone.cardinality;
+          const tooFew = shape.max < min;
+          const tooMany = max !== 'unbounded' && shape.min > max;
+          if (tooFew || tooMany)
+            context.report({
+              node: attribute ?? node.name,
+              messageId: 'cardinality',
+              data: {
+                component: key,
+                zone: zone.id,
+                cardinality: `${min}..${max}`,
+                count: tooFew ? shape.max : shape.min,
+              },
+            });
+        }
+      },
+    };
+  },
+};

package/lib/rules/ui-preferences.js

@@ -0,0 +1,63 @@
+import {
+  importRegistry,
+  isExcepted,
+  jsxKey,
+  loadUiContract,
+  UI_CONTRACT_LOAD_CODE,
+  UI_RULE_SCHEMA,
+} from '../ui-contract.js';
+
+const CODE = 'KUI-L301';
+
+export default {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Apply application-profile preferred UI component choices.',
+      url: 'https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/docs/rules/ui-preferences.md',
+    },
+    schema: UI_RULE_SCHEMA,
+    messages: {
+      config: `${UI_CONTRACT_LOAD_CODE}: Kerf UI catalog/profile could not be loaded: {{error}}`,
+      preferred:
+        'KUI-L301: `{{actual}}` is discouraged for `{{concept}}`; this profile prefers `{{preferred}}`. {{rationale}}',
+    },
+  },
+  create(context) {
+    const contract = loadUiContract(context);
+    const filename = context.filename ?? context.getFilename();
+    let registry;
+    return {
+      Program(node) {
+        if (contract.error)
+          context.report({
+            node,
+            messageId: 'config',
+            data: { error: contract.error },
+          });
+        else registry = importRegistry(node, contract);
+      },
+      JSXOpeningElement(node) {
+        if (!registry || isExcepted(contract, CODE, filename)) return;
+        const actual = jsxKey(node.name, registry, contract);
+        if (!actual) return;
+        for (const [concept, preference] of Object.entries(
+          contract.profile.preferences ?? {},
+        ))
+          if ((preference.avoid ?? []).includes(actual))
+            context.report({
+              node: node.name,
+              messageId: 'preferred',
+              data: {
+                actual,
+                concept,
+                preferred: preference.preferred,
+                rationale:
+                  preference.rationale ??
+                  'Use the project preference unless an exact profile exception applies.',
+              },
+            });
+      },
+    };
+  },
+};

package/lib/rules/ui-public-boundaries.js

@@ -0,0 +1,79 @@
+import {
+  isExcepted,
+  loadUiContract,
+  UI_CONTRACT_LOAD_CODE,
+  UI_RULE_SCHEMA,
+} from '../ui-contract.js';
+
+const CLASS_CODE = 'KUI-L101';
+const TOKEN_CODE = 'KUI-L102';
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Restrict Kerf UI classes and tokens to cataloged public boundaries.',
+      url: 'https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/docs/rules/ui-public-boundaries.md',
+    },
+    schema: UI_RULE_SCHEMA,
+    messages: {
+      config: `${UI_CONTRACT_LOAD_CODE}: Kerf UI catalog/profile could not be loaded: {{error}}`,
+      class:
+        'KUI-L101: `{{name}}` is private or uncataloged Kerf UI anatomy. Use a cataloged public class, prop, token, or component instead.',
+      token:
+        'KUI-L102: `{{name}}` is not a cataloged public Kerf UI token. Use a public semantic/component token.',
+    },
+  },
+  create(context) {
+    const contract = loadUiContract(context);
+    const filename = context.filename ?? context.getFilename();
+    let configured = false;
+    const inspect = (node, value, classContext = false) => {
+      if (typeof value !== 'string') return;
+      if (classContext && !isExcepted(contract, CLASS_CODE, filename))
+        for (const name of value
+          .split(/\s+/)
+          .filter((item) => item.startsWith('kui-')))
+          if (!contract.publicClasses.has(name))
+            context.report({ node, messageId: 'class', data: { name } });
+      if (!isExcepted(contract, TOKEN_CODE, filename))
+        for (const match of value.matchAll(/--kui-[a-z0-9-]+/g))
+          if (!contract.publicTokens.has(match[0]))
+            context.report({
+              node,
+              messageId: 'token',
+              data: { name: match[0] },
+            });
+    };
+    return {
+      Program(node) {
+        if (contract.error && !configured) {
+          configured = true;
+          context.report({
+            node,
+            messageId: 'config',
+            data: { error: contract.error },
+          });
+        }
+      },
+      JSXAttribute(node) {
+        if (contract.error || !['class', 'className'].includes(node.name?.name))
+          return;
+        if (node.value?.type === 'Literal')
+          inspect(node, node.value.value, true);
+        if (
+          node.value?.type === 'JSXExpressionContainer' &&
+          node.value.expression.type === 'Literal'
+        )
+          inspect(node, node.value.expression.value, true);
+      },
+      Literal(node) {
+        if (!contract.error) inspect(node, node.value, false);
+      },
+      TemplateElement(node) {
+        if (!contract.error) inspect(node, node.value.raw, false);
+      },
+    };
+  },
+};

package/lib/rules/ui-wiring.js

@@ -0,0 +1,102 @@
+import {
+  helperCall,
+  importRegistry,
+  isExcepted,
+  jsxKey,
+  loadUiContract,
+  UI_RULE_SCHEMA,
+  UI_CONTRACT_LOAD_CODE,
+} from '../ui-contract.js';
+
+const MISSING_CODE = 'KUI-L401';
+const CLEANUP_CODE = 'KUI-L402';
+
+const retained = (call) => call.parent?.type !== 'ExpressionStatement';
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Require cataloged Kerf UI wiring and retained cleanup.',
+      url: 'https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/docs/rules/ui-wiring.md',
+    },
+    schema: UI_RULE_SCHEMA,
+    messages: {
+      config: `${UI_CONTRACT_LOAD_CODE}: Kerf UI catalog/profile could not be loaded: {{error}}`,
+      missing:
+        'KUI-L401: `{{component}}` requires `{{helper}}`; import and invoke the documented wiring contract.',
+      cleanup:
+        'KUI-L402: Retain or return the disposer from `{{helper}}`; use `void` only for an intentional page-lifetime binding.',
+    },
+  },
+  create(context) {
+    const contract = loadUiContract(context);
+    const filename = context.filename ?? context.getFilename();
+    let registry;
+    const used = new Map();
+    const calls = new Map();
+    return {
+      Program(node) {
+        if (contract.error)
+          context.report({
+            node,
+            messageId: 'config',
+            data: { error: contract.error },
+          });
+        else registry = importRegistry(node, contract);
+      },
+      JSXOpeningElement(node) {
+        if (!registry) return;
+        const key = jsxKey(node.name, registry, contract);
+        if (key && !used.has(key)) used.set(key, node.name);
+      },
+      CallExpression(node) {
+        if (!registry) return;
+        const imported = helperCall(node.callee, registry, contract);
+        if (!imported) return;
+        const list = calls.get(imported.imported) ?? [];
+        list.push({ node, source: imported.source });
+        calls.set(imported.imported, list);
+      },
+      'Program:exit'(node) {
+        if (!registry) return;
+        for (const [key, usage] of used) {
+          const entry = contract.entries.get(key);
+          if (!entry?.wiring.required) continue;
+          for (const helper of entry.wiring.helpers) {
+            if (helper.startsWith('@')) {
+              if (
+                !registry.sources.has(helper) &&
+                !isExcepted(contract, MISSING_CODE, filename)
+              )
+                context.report({
+                  node: usage,
+                  messageId: 'missing',
+                  data: { component: key, helper },
+                });
+              continue;
+            }
+            const helperCalls = calls.get(helper) ?? [];
+            if (
+              !helperCalls.length &&
+              !isExcepted(contract, MISSING_CODE, filename)
+            )
+              context.report({
+                node: usage,
+                messageId: 'missing',
+                data: { component: key, helper },
+              });
+            if (!isExcepted(contract, CLEANUP_CODE, filename))
+              for (const { node: call } of helperCalls)
+                if (!retained(call))
+                  context.report({
+                    node: call,
+                    messageId: 'cleanup',
+                    data: { helper },
+                  });
+          }
+        }
+      },
+    };
+  },
+};

package/lib/ui-contract.js

@@ -0,0 +1,249 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import process from 'node:process';
+
+const PROFILE = '.kerf-ui-profile.json';
+const cache = new Map();
+const loadCommonJs = createRequire(import.meta.url);
+
+export const UI_CONTRACT_LOAD_CODE = 'KUI-L090';
+
+const readJson = (path) => JSON.parse(readFileSync(path, 'utf8'));
+
+function packageAsset(cwd, name) {
+  try {
+    return createRequire(resolve(cwd, 'package.json')).resolve(
+      `@kerfjs/ui/ai/${name}`,
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+function discoveredProfiles(cwd, filename, settings) {
+  if (settings.profile)
+    return [
+      {
+        source: '<eslint settings kerfjs.ui.profile>',
+        profile: settings.profile,
+      },
+    ];
+  const layers = [];
+  const add = (path, expectedScope) => {
+    const profile = readJson(path);
+    if (profile.scope !== expectedScope)
+      throw new Error(
+        `${path} must have profile scope ${expectedScope}, received ${profile.scope ?? 'missing'}`,
+      );
+    layers.push({ source: path, profile });
+  };
+  const defaultsPath =
+    settings.profileDefaultsPath ??
+    packageAsset(cwd, 'application-ui-profile.defaults.json');
+  if (defaultsPath && existsSync(defaultsPath)) add(defaultsPath, 'package');
+  const workspace = resolve(settings.workspaceRoot ?? cwd);
+  const target = resolve(dirname(filename));
+  if (relative(workspace, target).startsWith('..')) return layers;
+  const directories = [];
+  let directory = target;
+  while (true) {
+    directories.push(directory);
+    if (directory === workspace) break;
+    directory = dirname(directory);
+  }
+  for (const candidate of directories.reverse()) {
+    const path = resolve(candidate, PROFILE);
+    if (existsSync(path))
+      add(path, candidate === workspace ? 'workspace' : 'directory');
+  }
+  return layers;
+}
+
+export function loadUiContract(context) {
+  const settings = context.settings?.kerfjs?.ui ?? {};
+  const cwd = settings.workspaceRoot ?? context.cwd ?? process.cwd();
+  const filename = context.filename ?? context.getFilename();
+  const key = JSON.stringify([cwd, filename, settings]);
+  if (cache.has(key)) return cache.get(key);
+  try {
+    const catalog =
+      settings.catalog ??
+      readJson(
+        settings.catalogPath ?? packageAsset(cwd, 'component-catalog-v2.json'),
+      );
+    const selection =
+      settings.selectionCatalog ??
+      readJson(
+        settings.selectionCatalogPath ??
+          packageAsset(cwd, 'component-catalog.json'),
+      );
+    const profiles = settings.profilePath
+      ? [
+          {
+            source: settings.profilePath,
+            profile: readJson(settings.profilePath),
+          },
+        ]
+      : discoveredProfiles(cwd, filename, settings);
+    const profileContractPath =
+      settings.profileContractPath ??
+      packageAsset(cwd, 'application-ui-profile-sync.cjs');
+    if (!profileContractPath)
+      throw new Error(
+        'Cannot resolve @kerfjs/ui/ai/application-ui-profile-sync.cjs; install @kerfjs/ui or set kerfjs.ui.profileContractPath.',
+      );
+    const { loadApplicationUiProfileSync } = loadCommonJs(profileContractPath);
+    const diagnosticRegistryPath =
+      settings.diagnosticRegistryPath ??
+      resolve(
+        dirname(profileContractPath),
+        'application-ui-diagnostic-ids-v1.json',
+      );
+    const diagnosticRegistry = readJson(diagnosticRegistryPath);
+    if (
+      diagnosticRegistry.schemaVersion !== 1 ||
+      !Array.isArray(diagnosticRegistry.ids)
+    )
+      throw new Error(
+        `${diagnosticRegistryPath} must be an application UI diagnostic registry with schemaVersion 1.`,
+      );
+    const loadedProfile = loadApplicationUiProfileSync(profiles, {
+      fallbackCatalogs: [catalog],
+      knownRules: diagnosticRegistry.ids,
+    });
+    if (loadedProfile.diagnostics.length) {
+      const diagnostic = loadedProfile.diagnostics[0];
+      throw new Error(
+        `${diagnostic.source} ${diagnostic.path} ${diagnostic.code}: ${diagnostic.message}`,
+      );
+    }
+    const profile = loadedProfile.profile;
+    const entries = new Map(catalog.entries.map((entry) => [entry.key, entry]));
+    const imports = new Map();
+    const exports = new Map();
+    const helperSources = new Map();
+    const addHelperSource = (name, source) => {
+      const sources = helperSources.get(name) ?? new Set();
+      sources.add(source);
+      helperSources.set(name, sources);
+    };
+    for (const entry of selection.entries) {
+      const key = `${selection.package}:${entry.id}`;
+      if (entry.delivery?.browserImport)
+        imports.set(entry.delivery.browserImport, key);
+      for (const name of entry.publicExports ?? []) {
+        exports.set(name, key);
+        addHelperSource(name, selection.package);
+      }
+      for (const wiring of entry.wiring ?? [])
+        addHelperSource(wiring.export, wiring.import);
+    }
+    const value = {
+      entries,
+      package: selection.package,
+      imports,
+      exports,
+      helperSources,
+      profile,
+      cwd,
+      publicClasses: new Set(
+        catalog.entries.flatMap((entry) => entry.boundaries.publicClasses),
+      ),
+      publicTokens: new Set(
+        catalog.entries.flatMap((entry) => entry.boundaries.publicTokens),
+      ),
+      error: undefined,
+    };
+    cache.set(key, value);
+    return value;
+  } catch (error) {
+    const value = { error: error.message };
+    cache.set(key, value);
+    return value;
+  }
+}
+
+export function importRegistry(program, contract) {
+  const locals = new Map();
+  const namespaces = new Map();
+  const helpers = new Map();
+  const sources = new Set();
+  for (const node of program.body) {
+    if (node.type !== 'ImportDeclaration') continue;
+    const source = node.source.value;
+    sources.add(source);
+    const directKey = contract.imports?.get(source);
+    for (const specifier of node.specifiers) {
+      if (specifier.type === 'ImportNamespaceSpecifier') {
+        namespaces.set(specifier.local.name, source);
+        continue;
+      }
+      const imported =
+        specifier.type === 'ImportDefaultSpecifier'
+          ? 'default'
+          : (specifier.imported.name ?? specifier.imported.value);
+      const key =
+        directKey ??
+        (source === contract.package
+          ? contract.exports?.get(imported)
+          : undefined);
+      if (key) locals.set(specifier.local.name, key);
+      helpers.set(specifier.local.name, { imported, source });
+    }
+  }
+  return { locals, namespaces, helpers, sources };
+}
+
+export function jsxKey(name, registry, contract) {
+  if (name.type === 'JSXIdentifier') return registry.locals.get(name.name);
+  if (
+    name.type === 'JSXMemberExpression' &&
+    name.object.type === 'JSXIdentifier' &&
+    name.property.type === 'JSXIdentifier' &&
+    registry.namespaces.has(name.object.name)
+  ) {
+    const source = registry.namespaces.get(name.object.name);
+    const exportedKey = contract.exports.get(name.property.name);
+    if (source === contract.package) return exportedKey;
+    if (contract.imports.get(source) === exportedKey) return exportedKey;
+  }
+  return undefined;
+}
+
+export function helperCall(callee, registry, contract) {
+  let imported;
+  let source;
+  if (callee.type === 'Identifier') {
+    ({ imported, source } = registry.helpers.get(callee.name) ?? {});
+  } else if (
+    callee.type === 'MemberExpression' &&
+    !callee.computed &&
+    callee.object.type === 'Identifier' &&
+    callee.property.type === 'Identifier'
+  ) {
+    imported = callee.property.name;
+    source = registry.namespaces.get(callee.object.name);
+  }
+  if (!imported || !source) return undefined;
+  return contract.helperSources.get(imported)?.has(source)
+    ? { imported, source }
+    : undefined;
+}
+
+export function isExcepted(contract, code, filename) {
+  const projectPath = relative(contract.cwd, filename).replaceAll('\\', '/');
+  return (contract.profile?.exceptions ?? []).some((exception) => {
+    if (!exception.rules.includes(code)) return false;
+    const target = exception.target.replace(/^\.\//, '').replace(/\/$/, '');
+    return projectPath === target || projectPath.startsWith(`${target}/`);
+  });
+}
+
+export const UI_RULE_SCHEMA = [
+  {
+    type: 'object',
+    properties: {},
+    additionalProperties: false,
+  },
+];

package/package.json

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