eslint-plugin-kerfjs 5.0.0-beta.60 → 5.0.0-beta.62

package/docs/rules/ui-composition.md

@@ -3,6 +3,7 @@
 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 about the child: it runs only for a child that resolves to a cataloged entry (or a declared wrapper's roots) whose parents are `listed`. Its direct JSX parent may be any element the rule can see: a cataloged component, a declared wrapper (which counts as each of its roots), an intrinsic element such as `<div>`, or an unresolved component, and any parent that is not a listed parent reports `KUI-L201`. 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.
+An additional JSX export from an entry can declare its own `jsxExports.<name>.parents` contract. It uses that placement instead of the entry's root placement and is opaque to zone matching, so an action link does not impersonate its enclosing control group.
 
 ## Application and third-party wrappers
 

package/index.js

@@ -14,7 +14,7 @@ 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.60' },
+  meta: { name: 'eslint-plugin-kerfjs', version: '5.0.0-beta.62' },
   rules: {
     'no-inline-jsx-event-handlers': noInlineJsxEventHandlers,
     'no-raw-with-dynamic-arg': noRawWithDynamicArg,

package/lib/rules/ui-composition.js

@@ -1,6 +1,7 @@
 import {
   importRegistry,
   isExcepted,
+  jsxExportName,
   jsxKey,
   loadUiContract,
   UI_CONTRACT_LOAD_CODE,
@@ -35,7 +36,17 @@ function zoneShape(node, registry, contract) {
   if (!node || node.type === 'JSXEmptyExpression') return emptyShape();
   if (node.type === 'JSXElement') {
     const key = jsxKey(node.openingElement.name, registry, contract);
-    const roots = contract.entries.get(key)?.rendersAs;
+    const entry = contract.entries.get(key);
+    const exportName = jsxExportName(node.openingElement.name, registry);
+    // A second JSX export from one package entry may have its own element
+    // shape. It must not impersonate the entry's root in a parent's zone.
+    if (entry?.jsxExports?.[exportName])
+      return {
+        min: 1,
+        max: 1,
+        items: [{ label: `${key}:${exportName}` }],
+      };
+    const roots = entry?.rendersAs;
     // A declared wrapper renders one of its roots, or nothing.
     if (roots?.length)
       return {
@@ -166,23 +177,36 @@ export default {
         const key = jsxKey(node.name, registry, contract);
         const entry = contract.entries.get(key);
         if (!entry) return;
+        const exportName = jsxExportName(node.name, registry);
+        const exportContract = entry.jsxExports?.[exportName];
         // A wrapper answers to its own parent contract and to each root's.
         // Report one violated requirement per placement, with roots first.
-        const placed = [
-          ...(entry.rendersAs ?? []).flatMap((root) => {
-            const rootEntry = contract.entries.get(root);
-            return rootEntry
-              ? [{ entry: rootEntry, child: `${key} (renders ${root})` }]
-              : [];
-          }),
-          { entry, child: key },
-        ].filter(
+        const placed = exportContract
+          ? [
+              {
+                entry: { ...entry, parents: exportContract.parents },
+                child: `${key}:${exportName}`,
+              },
+            ]
+          : [
+              ...(entry.rendersAs ?? []).flatMap((root) => {
+                const rootEntry = contract.entries.get(root);
+                return rootEntry
+                  ? [{ entry: rootEntry, child: `${key} (renders ${root})` }]
+                  : [];
+              }),
+              { entry, child: key },
+            ];
+        const constrained = placed.filter(
           ({ entry: placedEntry }) => placedEntry.parents?.mode === 'listed',
         );
-        if (placed.length && !isExcepted(contract, PARENT_CODE, filename)) {
+        if (
+          constrained.length &&
+          !isExcepted(contract, PARENT_CODE, filename)
+        ) {
           const parent = directParentKey(node, registry, contract);
           if (parent) {
-            const violation = placed.find(
+            const violation = constrained.find(
               ({ entry: placedEntry }) =>
                 !rootsOf(parent.key, contract).every((root) =>
                   placedEntry.parents.entries.includes(root),
@@ -199,7 +223,7 @@ export default {
               });
           }
         }
-        for (const zone of entry.zones ?? []) {
+        for (const zone of exportContract ? [] : (entry.zones ?? [])) {
           const bound = boundZone(node, zone, registry, contract);
           if (!bound) continue;
           const { node: reportNode, shape } = bound;

package/lib/ui-contract.js

@@ -481,6 +481,19 @@ export function jsxKey(name, registry, contract) {
   return undefined;
 }
 
+/** Imported export name behind a JSX tag, including aliases and namespaces. */
+export function jsxExportName(name, registry) {
+  if (name.type === 'JSXIdentifier')
+    return registry.helpers.get(name.name)?.imported;
+  if (
+    name.type === 'JSXMemberExpression' &&
+    name.object.type === 'JSXIdentifier' &&
+    name.property.type === 'JSXIdentifier'
+  )
+    return name.property.name;
+  return undefined;
+}
+
 // A custom element authored directly as a lowercase JSX tag resolves to its
 // selection-catalog entry. Kept separate from `jsxKey` so composition rules
 // keep treating raw elements as application-owned markup.

package/package.json

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