eslint-plugin-kerfjs 5.0.0-beta.52 → 5.0.0-beta.54

package/docs/rules/ui-composition.md

@@ -2,4 +2,46 @@
 
 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. 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.
+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.
+
+## Application and third-party wrappers
+
+Beyond `@kerfjs/ui`'s own catalog, the rule loads every composition catalog the
+resolved `.kerf-ui-profile.json` declares under `catalogs`. Their components
+resolve by package subpath (`import { GroupWrap } from '@acme/bits/group-wrap'`,
+matched to the entry's `publicExports`) or, for an application's own relative
+imports, by source file (matched to the entry's `source`, trying the TypeScript
+ESM extensions a `.js` specifier stands for). An export without a `subpath` (a
+private application's, which is never imported by package name) resolves only
+by source file.
+
+A relative import may also reach the source file through relative re-exports,
+the way apps import wrappers through a components barrel:
+`import { DemandSegmentsControl } from './components/index.js'` resolves when
+`index.ts` has `export { DemandSegmentsControl } from '../demand-segments-control.js'`,
+a renamed `export { X as Y } from …` (import `Y`), or `export * from …`, and
+through chains of them (a directory import tries its `index` file). Type-only
+and namespace (`export * as ns`) re-exports, a component defined in the barrel
+itself, and re-exports of anything the catalogs do not declare stay unresolved,
+and cycles stop without resolving.
+
+An entry that declares `rendersAs` (a wrapper that renders one of the listed
+cataloged roots, or nothing) is checked as those roots:
+
+- **Zones (`KUI-L202`):** the zone must accept every declared root.
+- **Parents (`KUI-L201`):** each root's listed parents apply where the wrapper
+  is placed, and a wrapper used as a parent counts as each of its roots.
+- **Cardinality (`KUI-L203`):** the wrapper counts as zero or one child, since
+  it may render nothing.
+
+```tsx
+import { Toolbar } from '@kerfjs/ui';
+import { DemandSegmentsControl } from './demand-segments-control.js';
+
+// Valid when the app's catalog declares
+// rendersAs: ["@kerfjs/ui:toolbar-control-group"].
+<Toolbar trailing={<DemandSegmentsControl />} />;
+```
+
+A wrapper without `rendersAs`, or one the profile's catalogs do not declare,
+is still an unknown element and reports `KUI-L202` in a cataloged zone.

package/index.js

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

package/lib/rules/ui-composition.js

@@ -35,6 +35,14 @@ 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;
+    // A declared wrapper renders one of its roots, or nothing.
+    if (roots?.length)
+      return {
+        min: 0,
+        max: 1,
+        items: [{ key, roots, label: `${key} (renders ${roots.join(' | ')})` }],
+      };
     return {
       min: 1,
       max: 1,
@@ -94,6 +102,11 @@ function directParentKey(node, registry, contract) {
     : undefined;
 }
 
+// The cataloged roots an element stands for: a declared wrapper's `rendersAs`,
+// otherwise the element's own entry.
+const rootsOf = (key, contract) =>
+  contract.entries.get(key)?.rendersAs ?? [key];
+
 function boundZone(openingElement, zone, registry, contract) {
   const prop = zone.jsx?.prop;
   if (!prop) return undefined;
@@ -146,24 +159,42 @@ export default {
             messageId: 'config',
             data: { error: contract.error },
           });
-        else registry = importRegistry(node, contract);
+        else registry = importRegistry(node, contract, filename);
       },
       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)
-        ) {
+        // A wrapper answers to its own parent contract and to each root's.
+        const placed = [
+          { entry, child: key },
+          ...(entry.rendersAs ?? []).flatMap((root) => {
+            const rootEntry = contract.entries.get(root);
+            return rootEntry
+              ? [{ entry: rootEntry, child: `${key} (renders ${root})` }]
+              : [];
+          }),
+        ].filter(
+          ({ entry: placedEntry }) => placedEntry.parents?.mode === 'listed',
+        );
+        if (placed.length && !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(', ') },
-            });
+          if (parent)
+            for (const { entry: placedEntry, child } of placed)
+              if (
+                !rootsOf(parent.key, contract).every((root) =>
+                  placedEntry.parents.entries.includes(root),
+                )
+              )
+                context.report({
+                  node: node.name,
+                  messageId: 'parent',
+                  data: {
+                    child,
+                    parents: placedEntry.parents.entries.join(', '),
+                  },
+                });
         }
         for (const zone of entry.zones ?? []) {
           const bound = boundZone(node, zone, registry, contract);
@@ -180,7 +211,11 @@ export default {
           );
           if (allowed.size && !isExcepted(contract, ZONE_CODE, filename))
             for (const child of shape.items)
-              if (!child.key || !allowed.has(child.key))
+              if (
+                child.roots
+                  ? !child.roots.every((root) => allowed.has(root))
+                  : !child.key || !allowed.has(child.key)
+              )
                 context.report({
                   node: reportNode,
                   messageId: 'zone',

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

@@ -206,7 +206,7 @@ export default {
             messageId: 'config',
             data: { error: loaded.error },
           });
-        else registry = importRegistry(node, loaded);
+        else registry = importRegistry(node, loaded, filename);
       },
       JSXOpeningElement(node) {
         if (!registry) return;

package/lib/rules/ui-preferences.js

@@ -35,7 +35,7 @@ export default {
             messageId: 'config',
             data: { error: contract.error },
           });
-        else registry = importRegistry(node, contract);
+        else registry = importRegistry(node, contract, filename);
       },
       JSXOpeningElement(node) {
         if (!registry || isExcepted(contract, CODE, filename)) return;

package/lib/rules/ui-wiring.js

@@ -43,7 +43,7 @@ export default {
             messageId: 'config',
             data: { error: contract.error },
           });
-        else registry = importRegistry(node, contract);
+        else registry = importRegistry(node, contract, filename);
       },
       JSXOpeningElement(node) {
         if (!registry) return;

package/lib/ui-contract.js

@@ -1,5 +1,5 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, relative, resolve } from 'node:path';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, extname, relative, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 import process from 'node:process';
 
@@ -25,6 +25,57 @@ export function isComponentExport(name) {
 
 const readJson = (path) => JSON.parse(readFileSync(path, 'utf8'));
 
+// The directory whose package.json names `packageName`, searched upward from a
+// catalog file; a catalog's `source` paths are relative to that package root.
+function packageRootOf(start, packageName) {
+  for (let directory = dirname(start); ; directory = dirname(directory)) {
+    const manifest = resolve(directory, 'package.json');
+    if (existsSync(manifest)) {
+      try {
+        if (readJson(manifest).name === packageName) return directory;
+      } catch {
+        // An unreadable manifest is not the owner; keep searching.
+      }
+    }
+    if (dirname(directory) === directory) return dirname(start);
+  }
+}
+
+const exportName = (item) => (typeof item === 'string' ? item : item?.name);
+
+// Application and third-party composition catalogs a profile declares, beyond
+// the @kerfjs/ui catalog the rules load directly. Their entries join the
+// contract, and their components resolve by package subpath (a bare import)
+// or by source file (an app's relative import).
+function profileCatalogs(loadedProfile, basePackage) {
+  const catalogs = [];
+  for (const catalog of loadedProfile.profile?.catalogs ?? []) {
+    if (catalog.package === basePackage) continue;
+    const owner = loadedProfile.provenance?.[`$catalogs.${catalog.package}`];
+    if (!owner || !catalog.composition?.path || owner.startsWith('<')) continue;
+    const path = resolve(dirname(owner), catalog.composition.path);
+    const artifact = readJson(path);
+    catalogs.push({ artifact, root: packageRootOf(path, catalog.package) });
+  }
+  return catalogs;
+}
+
+// The files a relative import specifier may name, in the order TypeScript's
+// ESM resolution tries them (a `.js` specifier also names its `.ts`/`.tsx`).
+const SCRIPT_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.mts', '.mjs'];
+export function relativeImportCandidates(fromFile, specifier) {
+  const base = resolve(dirname(fromFile), specifier);
+  const extension = extname(base);
+  const stem = SCRIPT_EXTENSIONS.includes(extension)
+    ? base.slice(0, -extension.length)
+    : base;
+  return [
+    base,
+    ...SCRIPT_EXTENSIONS.map((candidate) => `${stem}${candidate}`),
+    ...SCRIPT_EXTENSIONS.map((candidate) => resolve(base, `index${candidate}`)),
+  ];
+}
+
 function packageAsset(cwd, name) {
   try {
     return createRequire(resolve(cwd, 'package.json')).resolve(
@@ -134,6 +185,35 @@ export function loadUiContract(context) {
     }
     const profile = loadedProfile.profile;
     const entries = new Map(catalog.entries.map((entry) => [entry.key, entry]));
+    // Declared application/third-party components: `packageExports` maps
+    // `<package or package/subpath>\0<Export>` and `sourceExports` maps
+    // `<absolute source file>\0<Export>` to the entry key.
+    const packageExports = new Map();
+    const sourceExports = new Map();
+    for (const { artifact, root } of profileCatalogs(
+      loadedProfile,
+      selection.package,
+    ))
+      for (const entry of artifact.entries ?? []) {
+        const key = entry.key ?? `${artifact.package}:${entry.id}`;
+        entries.set(key, entry);
+        for (const item of entry.publicExports ?? []) {
+          const name = exportName(item);
+          if (!name || !isComponentExport(name)) continue;
+          const subpath = typeof item === 'string' ? '.' : item.subpath;
+          // A private application's export has no subpath: it is never
+          // imported by package name, only through its source file below.
+          if (typeof subpath === 'string') {
+            const specifier =
+              subpath !== '.'
+                ? `${entry.package ?? artifact.package}/${subpath.replace(/^\.\//, '')}`
+                : (entry.package ?? artifact.package);
+            packageExports.set(`${specifier}\0${name}`, key);
+          }
+          if (entry.source)
+            sourceExports.set(`${resolve(root, entry.source)}\0${name}`, key);
+        }
+      }
     const imports = new Map();
     const exports = new Map();
     const helperSources = new Map();
@@ -160,6 +240,8 @@ export function loadUiContract(context) {
       package: selection.package,
       imports,
       exports,
+      packageExports,
+      sourceExports,
       helperSources,
       profile,
       cwd,
@@ -180,7 +262,7 @@ export function loadUiContract(context) {
   }
 }
 
-export function importRegistry(program, contract) {
+export function importRegistry(program, contract, filename) {
   const locals = new Map();
   const namespaces = new Map();
   const helpers = new Map();
@@ -204,7 +286,7 @@ export function importRegistry(program, contract) {
         : (directKey ??
           (source === contract.package
             ? contract.exports?.get(imported)
-            : undefined));
+            : declaredComponentKey(contract, source, imported, filename)));
       if (key) locals.set(specifier.local.name, key);
       helpers.set(specifier.local.name, { imported, source });
     }
@@ -212,6 +294,101 @@ export function importRegistry(program, contract) {
   return { locals, namespaces, helpers, sources };
 }
 
+// An application or third-party component declared in a profile catalog.
+function declaredComponentKey(contract, source, imported, filename) {
+  const byPackage = contract.packageExports?.get(`${source}\0${imported}`);
+  if (byPackage) return byPackage;
+  if (!filename || !source.startsWith('.') || !contract.sourceExports?.size)
+    return undefined;
+  return sourceComponentKey(contract, filename, source, imported, new Set());
+}
+
+// A relative import names a cataloged component by its defining source file,
+// or through relative re-exports (`export { X } from './x.js'`, `export * from
+// './x.js'`, chains of either) that reach one: apps commonly import wrappers
+// through a components barrel. Anything else — a bare re-export, a local
+// definition, a file that cannot be read — stays unresolved.
+const MAX_REEXPORT_VISITS = 64;
+function sourceComponentKey(contract, fromFile, specifier, imported, seen) {
+  const candidates = relativeImportCandidates(fromFile, specifier);
+  for (const candidate of candidates) {
+    const key = contract.sourceExports.get(`${candidate}\0${imported}`);
+    if (key) return key;
+  }
+  // `seen` holds each (file, name) already followed: it breaks re-export
+  // cycles and bounds the work a pathological barrel graph can cost.
+  if (seen.size >= MAX_REEXPORT_VISITS) return undefined;
+  for (const candidate of candidates) {
+    const reExports = relativeReExports(candidate);
+    if (!reExports) continue;
+    const visit = `${candidate}\0${imported}`;
+    if (seen.has(visit)) return undefined;
+    seen.add(visit);
+    for (const { name, local, from } of reExports) {
+      if (name !== undefined && name !== imported) continue;
+      const key = sourceComponentKey(
+        contract,
+        candidate,
+        from,
+        name === undefined ? imported : local,
+        seen,
+      );
+      if (key) return key;
+    }
+    // The first file that exists is the one the import resolves to.
+    return undefined;
+  }
+  return undefined;
+}
+
+// The relative value re-exports of one module file, read from its source text:
+// `{ name, local, from }` for `export { local as name } from`, and
+// `{ from }` (every name) for `export * from`. Type-only re-exports and
+// namespace re-exports (`export * as ns`) are skipped. Cached by modification
+// time, so a long-lived editor session sees barrel edits. Undefined when the
+// file does not exist.
+const reExportCache = new Map();
+function relativeReExports(file) {
+  let mtime;
+  try {
+    const stats = statSync(file);
+    if (!stats.isFile()) return undefined;
+    mtime = stats.mtimeMs;
+  } catch {
+    return undefined;
+  }
+  const cached = reExportCache.get(file);
+  if (cached?.mtime === mtime) return cached.reExports;
+  let text;
+  try {
+    text = readFileSync(file, 'utf8');
+  } catch {
+    return undefined;
+  }
+  const code = text
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/(^|[^:\\])\/\/[^\n]*/g, '$1');
+  const reExports = [];
+  const named = /\bexport\s+(type\s+)?\{([^}]*)\}\s*from\s*(['"])([^'"]+)\3/g;
+  for (const match of code.matchAll(named)) {
+    const [, typeOnly, list, , from] = match;
+    if (typeOnly || !from.startsWith('.')) continue;
+    for (const raw of list.split(',')) {
+      const part = raw.trim();
+      if (!part || /^type\s/.test(part)) continue;
+      const [local, name = local] = part.split(/\s+as\s+/).map((x) => x.trim());
+      reExports.push({ name, local, from });
+    }
+  }
+  const star = /\bexport\s+\*\s+from\s*(['"])([^'"]+)\1/g;
+  for (const match of code.matchAll(star)) {
+    const from = match[2];
+    if (from.startsWith('.')) reExports.push({ from });
+  }
+  reExportCache.set(file, { mtime, reExports });
+  return reExports;
+}
+
 export function jsxKey(name, registry, contract) {
   if (name.type === 'JSXIdentifier') return registry.locals.get(name.name);
   if (

package/package.json

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