eslint-plugin-kerfjs 5.0.0-beta.67 → 5.0.0-beta.69

package/docs/rules/ui-composition.md

@@ -5,6 +5,12 @@ Enforces composition facts published by the versioned UI catalog. `KUI-L201` rep
 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.
 
+`KUI-L202` inspects JSX written directly in a bound zone prop, including its
+fragments, arrays, and conditional branches. It does not follow a local binding
+such as `const actions = <div />; <TabBar trailing={actions} />`. Review those
+bindings against the zone's catalog contract; an unknown expression produces
+no zone-child diagnostic.
+
 ## Application and third-party wrappers
 
 Beyond `@kerfjs/ui`'s own catalog, the rule loads every composition catalog the

package/docs/rules/ui-wiring.md

@@ -2,4 +2,26 @@
 
 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.
 
+Declare application entry modules in the application UI profile to check root wiring once per entry:
+
+```json
+{ "schemaVersion": 1, "scope": "workspace", "wiring": { "entries": ["src/main.tsx"] } }
+```
+
+Entry paths are relative to the workspace root. The rule follows relative imports, re-exports, and literal dynamic imports from each entry. An application-scoped obligation is checked at the entry if any reachable module renders its component; a recognized helper call in any reachable module satisfies it. Reachable leaf modules need no duplicate wiring. A module outside every declared entry keeps the per-file check. A composition entry can set `wiring.scope` to `"module"` for a helper that must be installed beside its rendering code; omitted scope means `"application"`. Computed import paths and unresolved modules stay outside the static graph, so put them in a declared entry or check them separately. `KUI-L402` still checks the helper's call site.
+
+Consumer composition catalogs can name an application helper's defining file in `wiring.sources`:
+
+```json
+"wiring": {
+  "required": true,
+  "helpers": ["wireTicketSearch"],
+  "sources": [{ "export": "wireTicketSearch", "source": "src/interactions/ticket-search.ts" }]
+}
+```
+
+The source path is relative to the catalog package root. The rule resolves relative imports, aliases, and re-export barrels to that file, so another function with the same name does not satisfy the obligation.
+
+The selection catalog can declare a public wiring provider in `wiringProviders`, naming its export, import source, and the helpers it installs. A recognized `wireCatalog` call from `@kerfjs/ui/wire-catalog` provides `wireScrollDividers`, so the rule does not ask for a duplicate call on the same application entry. The provider's disposer still needs to be retained.
+
 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 component-catalog 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

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

package/lib/rules/ui-composition.js

@@ -1,4 +1,5 @@
 import {
+  customElementKey,
   importRegistry,
   isExcepted,
   jsxExportName,
@@ -35,7 +36,9 @@ function jsxLabel(name) {
 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 key =
+      jsxKey(node.openingElement.name, registry, contract) ??
+      customElementKey(node.openingElement.name, contract);
     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

package/lib/rules/ui-wiring.js

@@ -1,9 +1,13 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+
 import {
   helperCall,
   importRegistry,
   isExcepted,
   jsxKey,
   loadUiContract,
+  relativeImportCandidates,
   UI_RULE_SCHEMA,
   UI_CONTRACT_LOAD_CODE,
 } from '../ui-contract.js';
@@ -13,6 +17,155 @@ const CLEANUP_CODE = 'KUI-L402';
 
 const retained = (call) => call.parent?.type !== 'ExpressionStatement';
 
+const script = /\.(?:[cm]?[jt]sx?)$/;
+const imports =
+  /(?:^|[;\n])\s*(?:import|export)\s+(?:[^;'"`]*?\s+from\s*)?['"]([^'"]+)['"]/g;
+const dynamicImports = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+function entryModules(entryFile, currentFile, currentText) {
+  const modules = new Map();
+  const visit = (file) => {
+    if (modules.has(file)) return;
+    let source;
+    try {
+      source = file === currentFile ? currentText : readFileSync(file, 'utf8');
+    } catch {
+      return;
+    }
+    modules.set(file, source);
+    for (const [, specifier] of [
+      ...source.matchAll(imports),
+      ...source.matchAll(dynamicImports),
+    ]) {
+      if (!specifier.startsWith('.')) continue;
+      const dependency = relativeImportCandidates(file, specifier).find(
+        (candidate) => script.test(candidate) && existsSync(candidate),
+      );
+      if (dependency) visit(dependency);
+    }
+  };
+  visit(entryFile);
+  return modules;
+}
+
+// The entry graph is read from disk because ESLint visits one source file at a
+// time. Match only imported JSX names; an unrelated local tag cannot satisfy a
+// catalog obligation. The current entry's in-memory text covers editor linting.
+function moduleUses(source, file, contract) {
+  const uses = new Set();
+  const declarations = /\bimport\s+([^;'"`]*?)\s+from\s*['"]([^'"]+)['"]/g;
+  for (const [, bindings, from] of source.matchAll(declarations)) {
+    const direct = contract.imports.get(from);
+    const keyFor = (name) =>
+      direct ??
+      (from === contract.package ? contract.exports.get(name) : undefined) ??
+      contract.packageExports.get(`${from}\0${name}`) ??
+      (from.startsWith('.')
+        ? relativeImportCandidates(file, from)
+            .map((candidate) =>
+              contract.sourceExports.get(`${candidate}\0${name}`),
+            )
+            .find(Boolean)
+        : undefined);
+    const named = bindings.match(/\{([^}]*)\}/)?.[1];
+    if (named)
+      for (const part of named.split(',')) {
+        const match = part.trim().match(/^(\w+)(?:\s+as\s+(\w+))?$/);
+        if (!match) continue;
+        const [, imported, local = imported] = match;
+        const key = keyFor(imported);
+        if (key && new RegExp(`<${local}(?=[\\s/>])`).test(source))
+          uses.add(key);
+      }
+    const namespace = bindings.match(/\*\s+as\s+(\w+)/)?.[1];
+    if (namespace) {
+      const names = new Set([
+        ...contract.exports.keys(),
+        ...[...contract.packageExports.keys()].map((key) => key.split('\0')[1]),
+      ]);
+      for (const name of names) {
+        const key = keyFor(name);
+        if (
+          key &&
+          new RegExp(`<${namespace}\\.${name}(?=[\\s/>])`).test(source)
+        )
+          uses.add(key);
+      }
+    }
+    const defaultName = bindings.match(/^\s*(\w+)\s*(?:,|$)/)?.[1];
+    if (
+      direct &&
+      defaultName &&
+      new RegExp(`<${defaultName}(?=[\\s/>])`).test(source)
+    )
+      uses.add(direct);
+  }
+  return uses;
+}
+
+// ESLint supplies an AST only for the file currently being linted. For other
+// files in an entry graph, recognize imported helper calls by their local
+// binding (including aliases and namespace imports) and resolved source.
+function moduleCalls(source, file, contract) {
+  const calls = new Set();
+  // Keep import declarations intact, but exclude comments and literals from
+  // the call search so a documented example cannot satisfy an obligation.
+  const callableText = source.replace(
+    /\/\*[\s\S]*?\*\/|\/\/[^\n]*|(['"`])(?:\\.|(?!\1)[^\\])*?\1/g,
+    (match) => match.replace(/[^\n]/g, ' '),
+  );
+  const declarations = /\bimport\s+([^;'"`]*?)\s+from\s*['"]([^'"]+)['"]/g;
+  for (const [, bindings, from] of source.matchAll(declarations)) {
+    const named = bindings.match(/\{([^}]*)\}/)?.[1];
+    if (named)
+      for (const part of named.split(',')) {
+        const match = part.trim().match(/^(\w+)(?:\s+as\s+(\w+))?$/);
+        if (!match) continue;
+        const [, imported, local = imported] = match;
+        if (new RegExp(`\\b${local}\\s*\\(`).test(callableText)) {
+          const recognized = helperCall(
+            { type: 'Identifier', name: local },
+            { helpers: new Map([[local, { imported, source: from }]]) },
+            contract,
+            file,
+          );
+          if (recognized) calls.add(recognized.imported);
+        }
+      }
+    const namespace = bindings.match(/\*\s+as\s+(\w+)/)?.[1];
+    if (namespace)
+      for (const [, helper] of callableText.matchAll(
+        new RegExp(`\\b${namespace}\\.(\\w+)\\s*\\(`, 'g'),
+      )) {
+        const recognized = helperCall(
+          {
+            type: 'MemberExpression',
+            computed: false,
+            object: { type: 'Identifier', name: namespace },
+            property: { type: 'Identifier', name: helper },
+          },
+          { namespaces: new Map([[namespace, from]]) },
+          contract,
+          file,
+        );
+        if (recognized) calls.add(recognized.imported);
+      }
+  }
+  return calls;
+}
+
+function applicationEntries(contract, filename, source) {
+  const root = resolve(contract.cwd);
+  const entries = [];
+  for (const path of contract.profile.wiring?.entries ?? []) {
+    const file = resolve(root, path);
+    if (relative(root, file).startsWith('..')) continue;
+    const modules = entryModules(file, filename, source);
+    if (modules.size) entries.push({ file, modules });
+  }
+  return entries;
+}
+
 export default {
   meta: {
     type: 'problem',
@@ -52,7 +205,7 @@ export default {
       },
       CallExpression(node) {
         if (!registry) return;
-        const imported = helperCall(node.callee, registry, contract);
+        const imported = helperCall(node.callee, registry, contract, filename);
         if (!imported) return;
         const list = calls.get(imported.imported) ?? [];
         list.push({ node, source: imported.source });
@@ -60,9 +213,32 @@ export default {
       },
       'Program:exit'(node) {
         if (!registry) return;
-        for (const [key, usage] of used) {
+        const entries = applicationEntries(
+          contract,
+          filename,
+          context.sourceCode.text,
+        );
+        const reachable = entries.filter(({ modules }) =>
+          modules.has(filename),
+        );
+        const ownEntry = entries.find(({ file }) => file === filename);
+        const reachableCalls = new Set(calls.keys());
+        if (ownEntry)
+          for (const [file, source] of ownEntry.modules)
+            if (file !== filename)
+              for (const helper of moduleCalls(source, file, contract))
+                reachableCalls.add(helper);
+        const required = new Map(used);
+        if (ownEntry)
+          for (const [file, source] of ownEntry.modules)
+            for (const key of moduleUses(source, file, contract))
+              if (!required.has(key)) required.set(key, node);
+        for (const [key, usage] of required) {
           const entry = contract.entries.get(key);
           if (!entry?.wiring.required) continue;
+          if (entry.wiring.scope === 'module' && !used.has(key)) continue;
+          if (entry.wiring.scope !== 'module' && reachable.length && !ownEntry)
+            continue;
           for (const helper of entry.wiring.helpers) {
             if (helper.startsWith('@')) {
               if (
@@ -76,17 +252,27 @@ export default {
                 });
               continue;
             }
-            const helperCalls = calls.get(helper) ?? [];
-            if (
-              !helperCalls.length &&
-              !isExcepted(contract, MISSING_CODE, filename)
-            )
+            const providers = contract.helperProviders.get(helper) ?? new Set();
+            const provided = [helper, ...providers].some((name) =>
+              ownEntry ? reachableCalls.has(name) : calls.has(name),
+            );
+            if (!provided && !isExcepted(contract, MISSING_CODE, filename))
               context.report({
                 node: usage,
                 messageId: 'missing',
                 data: { component: key, helper },
               });
-            if (!isExcepted(contract, CLEANUP_CODE, filename))
+          }
+        }
+        if (!isExcepted(contract, CLEANUP_CODE, filename)) {
+          const disposerHelpers = new Set(
+            [...contract.entries.values()]
+              .filter((entry) => entry.wiring?.required)
+              .flatMap((entry) => entry.wiring.helpers)
+              .filter((helper) => !helper.startsWith('@')),
+          );
+          for (const [helper, helperCalls] of calls)
+            if (disposerHelpers.has(helper))
               for (const { node: call } of helperCalls)
                 if (!retained(call))
                   context.report({
@@ -94,7 +280,6 @@ export default {
                     messageId: 'cleanup',
                     data: { helper },
                   });
-          }
         }
       },
     };

package/lib/ui-contract.js

@@ -208,6 +208,7 @@ export function loadUiContract(context) {
     // `<absolute source file>\0<Export>` to the entry key.
     const packageExports = new Map();
     const sourceExports = new Map();
+    const helperSourceFiles = new Map();
     // Source files of declared components: a wrapper's own source may render
     // the element it wraps (Kerf's PopupMenu renders `wa-dropdown`).
     const componentSources = new Set();
@@ -253,6 +254,11 @@ export function loadUiContract(context) {
             componentSources.add(resolve(root, entry.source));
           }
         }
+        for (const helper of entry.wiring?.sources ?? [])
+          helperSourceFiles.set(
+            `${resolve(root, helper.source)}\0${helper.export}`,
+            helper.export,
+          );
       }
     const imports = new Map();
     const exports = new Map();
@@ -260,6 +266,7 @@ export function loadUiContract(context) {
     // (`<wa-dropdown>`) rather than through an imported component.
     const customElements = new Map();
     const helperSources = new Map();
+    const helperProviders = new Map();
     const addHelperSource = (name, source) => {
       const sources = helperSources.get(name) ?? new Set();
       sources.add(source);
@@ -279,6 +286,14 @@ export function loadUiContract(context) {
       for (const wiring of entry.wiring ?? [])
         addHelperSource(wiring.export, wiring.import);
     }
+    for (const provider of selection.wiringProviders ?? []) {
+      addHelperSource(provider.export, provider.import);
+      for (const helper of provider.provides) {
+        const providers = helperProviders.get(helper) ?? new Set();
+        providers.add(provider.export);
+        helperProviders.set(helper, providers);
+      }
+    }
     const value = {
       entries,
       package: selection.package,
@@ -289,6 +304,8 @@ export function loadUiContract(context) {
       componentSources,
       customElements,
       helperSources,
+      helperProviders,
+      helperSourceFiles,
       profile,
       cwd,
       publicClasses: new Set(
@@ -386,9 +403,19 @@ function declaredComponentKey(contract, source, imported, filename) {
 // definition, a file that cannot be read — stays unresolved.
 const MAX_REEXPORT_VISITS = 64;
 function sourceComponentKey(contract, fromFile, specifier, imported, seen) {
+  return sourceExportKey(
+    contract.sourceExports,
+    fromFile,
+    specifier,
+    imported,
+    seen,
+  );
+}
+
+function sourceExportKey(exports, fromFile, specifier, imported, seen) {
   const candidates = relativeImportCandidates(fromFile, specifier);
   for (const candidate of candidates) {
-    const key = contract.sourceExports.get(`${candidate}\0${imported}`);
+    const key = exports.get(`${candidate}\0${imported}`);
     if (key) return key;
   }
   // `seen` holds each (file, name) already followed: it breaks re-export
@@ -402,8 +429,8 @@ function sourceComponentKey(contract, fromFile, specifier, imported, seen) {
     seen.add(visit);
     for (const { name, local, from } of reExports) {
       if (name !== undefined && name !== imported) continue;
-      const key = sourceComponentKey(
-        contract,
+      const key = sourceExportKey(
+        exports,
         candidate,
         from,
         name === undefined ? imported : local,
@@ -502,7 +529,7 @@ export function customElementKey(name, contract) {
   return contract.customElements?.get(name.name);
 }
 
-export function helperCall(callee, registry, contract) {
+export function helperCall(callee, registry, contract, filename) {
   let imported;
   let source;
   if (callee.type === 'Identifier') {
@@ -517,9 +544,19 @@ export function helperCall(callee, registry, contract) {
     source = registry.namespaces.get(callee.object.name);
   }
   if (!imported || !source) return undefined;
-  return contract.helperSources.get(imported)?.has(source)
-    ? { imported, source }
-    : undefined;
+  if (contract.helperSources.get(imported)?.has(source))
+    return { imported, source };
+  if (filename && source.startsWith('.') && contract.helperSourceFiles?.size) {
+    const resolved = sourceExportKey(
+      contract.helperSourceFiles,
+      filename,
+      source,
+      imported,
+      new Set(),
+    );
+    if (resolved) return { imported: resolved, source };
+  }
+  return undefined;
 }
 
 export function isExcepted(contract, code, filename) {

package/package.json

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