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

package/docs/rules/ui-wiring.md

@@ -2,4 +2,12 @@
 
 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; 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.
+
 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.68' },
   rules: {
     'no-inline-jsx-event-handlers': noInlineJsxEventHandlers,
     'no-raw-with-dynamic-arg': noRawWithDynamicArg,

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,104 @@ 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;
+}
+
+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',
@@ -60,9 +162,26 @@ 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 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 (
@@ -86,7 +205,17 @@ export default {
                 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 +223,6 @@ export default {
                     messageId: 'cleanup',
                     data: { helper },
                   });
-          }
         }
       },
     };

package/package.json

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