eslint-plugin-kerfjs 4.4.0 → 4.5.0-beta.1

package/lib/rules/no-raw-with-dynamic-arg.js

@@ -22,13 +22,13 @@ const meta = {
   type: 'problem',
   docs: {
     description:
-      "Disallow `raw()` with dynamic arguments; `raw()` bypasses HTML escaping and passing dynamic values is an XSS vector.",
+      'Disallow `raw()` with dynamic arguments; `raw()` bypasses HTML escaping and passing dynamic values is an XSS vector.',
     url: 'https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/docs/rules/no-raw-with-dynamic-arg.md',
   },
   schema: [],
   messages: {
     dynamic:
-      "`raw()` bypasses HTML auto-escaping. Passing a dynamic value is an XSS risk unless the input has been sanitized. Sanitize first (`DOMPurify.sanitize(...)`) then pass to `raw()`, or add `// eslint-disable-next-line kerfjs/no-raw-with-dynamic-arg` to mark a call as intentionally safe.",
+      '`raw()` bypasses HTML auto-escaping. Passing a dynamic value is an XSS risk unless the input has been sanitized. Sanitize first (`DOMPurify.sanitize(...)`) then pass to `raw()`, or add `// eslint-disable-next-line kerfjs/no-raw-with-dynamic-arg` to mark a call as intentionally safe.',
   },
 };
 
@@ -47,10 +47,11 @@ function create(context) {
       const callee = node.callee;
       if (!callee) return;
       // Match bare `raw(...)` and `kerfjs.raw(...)` / `kerf.raw(...)` shapes.
-      const isRaw = (callee.type === 'Identifier' && callee.name === 'raw')
-        || (callee.type === 'MemberExpression'
-            && callee.property.type === 'Identifier'
-            && callee.property.name === 'raw');
+      const isRaw =
+        (callee.type === 'Identifier' && callee.name === 'raw') ||
+        (callee.type === 'MemberExpression' &&
+          callee.property.type === 'Identifier' &&
+          callee.property.name === 'raw');
       if (!isRaw) return;
       if (node.arguments.length === 0) return;
       const arg = node.arguments[0];

package/lib/rules/prefer-module-jsx-augmentation.js

@@ -10,7 +10,8 @@ function findGlobalJSXIntrinsics(moduleBlock) {
   for (const m of moduleBlock.body) {
     if (m.type !== 'TSModuleDeclaration') continue;
     const idNode = m.id;
-    if (!idNode || idNode.type !== 'Identifier' || idNode.name !== 'JSX') continue;
+    if (!idNode || idNode.type !== 'Identifier' || idNode.name !== 'JSX')
+      continue;
     const inner = m.body;
     if (!inner || inner.type !== 'TSModuleBlock') continue;
     for (const member of inner.body) {
@@ -31,7 +32,7 @@ const meta = {
   type: 'problem',
   docs: {
     description:
-      "Declaration-merge `JSX.IntrinsicElements` into `kerfjs/jsx-runtime`, not the global namespace.",
+      'Declaration-merge `JSX.IntrinsicElements` into `kerfjs/jsx-runtime`, not the global namespace.',
     url: 'https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/docs/rules/prefer-module-jsx-augmentation.md',
   },
   schema: [],

package/lib/rules/require-data-key-in-each.js

@@ -38,10 +38,15 @@ const meta = {
 function create(context) {
   return {
     CallExpression(node) {
-      if (node.callee.type !== 'Identifier' || node.callee.name !== 'each') return;
+      if (node.callee.type !== 'Identifier' || node.callee.name !== 'each')
+        return;
       const cb = node.arguments[1];
       if (!cb) return;
-      if (cb.type !== 'ArrowFunctionExpression' && cb.type !== 'FunctionExpression') return;
+      if (
+        cb.type !== 'ArrowFunctionExpression' &&
+        cb.type !== 'FunctionExpression'
+      )
+        return;
       const root = findRootJSXFromBody(cb.body);
       if (!root) return;
       if (root.type === 'JSXFragment') {

package/lib/rules/require-delegate-disposer.js

@@ -52,7 +52,8 @@ function create(context) {
       // the disposer is being routed somewhere reachable — accept.
       const parent = node.parent;
       if (!parent) return;
-      if (parent.type === 'UnaryExpression' && parent.operator === 'void') return;
+      if (parent.type === 'UnaryExpression' && parent.operator === 'void')
+        return;
       if (parent.type !== 'ExpressionStatement') return;
 
       context.report({

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 },
+                  });
+          }
+        }
+      },
+    };
+  },
+};