@nadicodeai/ui 1.0.1 → 1.1.0

package/dist/eslint/rules/jsx-class-utility.js

@@ -1,204 +1,181 @@
-const PACKAGE_PRIMITIVE_PATH = "@nadicodeai/ui/src/";
+/*
+ * The one className reader the plugin's class rules share.
+ *
+ * It reads LITERALS: string literals and template quasis anywhere inside a
+ * `className` expression, plus the class strings a `cva()` call carries. On top
+ * of that it takes EXACTLY ONE HOP: an identifier resolves to a same-file
+ * `const` string literal, and an identifier or a `TABLE.key` lookup resolves to
+ * a same-file `const` object whose string values are then read as classes. A
+ * `{...props}` spread resolves the same way and contributes that object's
+ * `className` value alone.
+ *
+ * One hop, and no further: nothing chains through a second binding, nothing
+ * crosses a file, nothing evaluates a condition or a template, and no value the
+ * hop cannot see is guessed at. That is the minimum that holds the package
+ * contract's repaint ban (`packages/ui/docs/contract.md`) against the way
+ * this repository actually authors classes — a tone table beside its component
+ * and a lookup at the call site, as in
+ * `apps/portal/src/components/portal-overview/overview-usage-tone.ts`. Without the
+ * hop, `<Card className={tones.warning} />` repaints a primitive and no rule
+ * sees it; with it, the table's own values are read.
+ *
+ * Standard tool checked (ADR 0057 tier 2): `eslint-plugin-better-tailwindcss`
+ * reads lookup tables through a `variable` selector with an `objectValues`
+ * matcher, and the root config uses exactly that so a table's classes are
+ * checked for existence. What it cannot do is say WHERE a value lands: its
+ * rules judge a class on its own, never against the JSX element it is applied
+ * to. "Not on an imported primitive" is a relationship between a class and an
+ * element, so it stays here.
+ *
+ * Anything past one hop remains out of reach by design and is a review finding,
+ * not a lint finding.
+ */
+
+/** The same-file binding an identifier refers to, or undefined. */
+function findVariable(scope, name) {
+  for (let current = scope; current; current = current.upper) {
+    const variable = current.set.get(name);
+    if (variable) return variable;
+  }
+  return undefined;
+}
 
-export function isPackageOwnedPrimitive(filename) {
-  return filename.replaceAll("\\", "/").includes(PACKAGE_PRIMITIVE_PATH);
+/**
+ * The initializer of the same-file `const` an identifier names. Undefined for
+ * imports, parameters, `let`/`var`, and anything declared more than once —
+ * every shape whose value is not fixed by this file alone.
+ */
+function constInitializer(identifier, context) {
+  if (!context?.sourceCode) return undefined;
+  const variable = findVariable(context.sourceCode.getScope(identifier), identifier.name);
+  if (!variable || variable.defs.length !== 1) return undefined;
+  const [definition] = variable.defs;
+  if (definition.type !== "Variable" || definition.parent?.kind !== "const") return undefined;
+  return definition.node.init ?? undefined;
 }
 
-function variableInitializer(node, context) {
-  let scope = context.sourceCode.getScope(node);
-  while (scope) {
-    const variable = scope.set.get(node.name);
-    const definition = variable?.defs.find(
-      (candidate) => candidate.type === "Variable" && candidate.node?.type === "VariableDeclarator",
-    );
-    if (definition?.node.init) return definition.node.init;
-    scope = scope.upper;
+/** Every string-literal value of an object literal; a lookup can select any of them. */
+function objectStringValues(objectExpression) {
+  const values = [];
+  for (const property of objectExpression.properties) {
+    if (property.type !== "Property") continue;
+    if (property.value.type === "Literal" && typeof property.value.value === "string") {
+      values.push(property.value.value);
+    }
   }
-  return undefined;
+  return values;
 }
 
-function collectStaticClassFragments(
-  node,
-  fragments,
-  context,
-  seen = new Set(),
-  includeObjectKeys = true,
-) {
-  if (!node) return;
+/** The one hop: the class strings a resolved `const` contributes, if any. */
+function resolvedFragments(identifier, context, { objectsOnly = false } = {}) {
+  const initializer = constInitializer(identifier, context);
+  if (!initializer) return [];
+  if (initializer.type === "ObjectExpression") return objectStringValues(initializer);
+  if (objectsOnly) return [];
+  return initializer.type === "Literal" && typeof initializer.value === "string"
+    ? [initializer.value]
+    : [];
+}
 
-  if (seen.has(node)) return;
-  seen.add(node);
+/** Every string literal and template chunk in the subtree, in source order. */
+function literalFragments(node, fragments, { skipPropertyKeys, context }) {
+  if (!node || typeof node.type !== "string") return;
 
-  if (node.type === "Literal" && typeof node.value === "string") {
-    fragments.push(node.value);
-    return;
-  }
-  if (node.type === "JSXExpressionContainer" || node.type === "ChainExpression") {
-    collectStaticClassFragments(node.expression, fragments, context, seen, includeObjectKeys);
+  if (node.type === "Literal") {
+    if (typeof node.value === "string") fragments.push(node.value);
     return;
   }
-  if (node.type === "TemplateLiteral") {
-    for (const quasi of node.quasis) fragments.push(quasi.value.cooked ?? quasi.value.raw);
-    for (const expression of node.expressions) {
-      collectStaticClassFragments(expression, fragments, context, seen, includeObjectKeys);
-    }
-    return;
-  }
-  if (node.type === "TaggedTemplateExpression") {
-    collectStaticClassFragments(node.quasi, fragments, context, seen, includeObjectKeys);
-    return;
-  }
-  if (node.type === "ConditionalExpression") {
-    collectStaticClassFragments(node.consequent, fragments, context, seen, includeObjectKeys);
-    collectStaticClassFragments(node.alternate, fragments, context, seen, includeObjectKeys);
-    return;
-  }
-  if (node.type === "LogicalExpression" || node.type === "BinaryExpression") {
-    collectStaticClassFragments(node.left, fragments, context, seen, includeObjectKeys);
-    collectStaticClassFragments(node.right, fragments, context, seen, includeObjectKeys);
+  if (node.type === "TemplateElement") {
+    fragments.push(node.value.cooked ?? node.value.raw);
     return;
   }
-  if (node.type === "CallExpression" || node.type === "NewExpression") {
-    for (const argument of node.arguments) {
-      collectStaticClassFragments(
-        argument.type === "SpreadElement" ? argument.argument : argument,
-        fragments,
-        context,
-        seen,
-        includeObjectKeys,
-      );
-    }
-    return;
-  }
-  if (node.type === "ArrayExpression" || node.type === "SequenceExpression") {
-    for (const element of node.elements ?? node.expressions) {
-      collectStaticClassFragments(
-        element?.type === "SpreadElement" ? element.argument : element,
-        fragments,
-        context,
-        seen,
-        includeObjectKeys,
-      );
-    }
-    return;
-  }
-  if (node.type === "ObjectExpression") {
-    for (const property of node.properties) {
-      if (property.type === "SpreadElement") {
-        collectStaticClassFragments(property.argument, fragments, context, seen, includeObjectKeys);
-        continue;
-      }
-      if (includeObjectKeys && !property.computed) {
-        collectStaticClassFragments(property.key, fragments, context, seen, includeObjectKeys);
-      }
-      collectStaticClassFragments(property.value, fragments, context, seen, includeObjectKeys);
+  // `USAGE_TONE_CLASS[kpi.tone ?? "normal"]` selects a class string, it does
+  // not contain one: the names inside the lookup are keys. The hop reads the
+  // table instead — any of its values can be the one selected — and the
+  // property is never descended into.
+  if (node.type === "MemberExpression") {
+    if (node.object.type === "Identifier") {
+      fragments.push(...resolvedFragments(node.object, context, { objectsOnly: true }));
     }
     return;
   }
   if (node.type === "Identifier") {
-    collectStaticClassFragments(
-      variableInitializer(node, context),
-      fragments,
-      context,
-      seen,
-      includeObjectKeys,
-    );
+    fragments.push(...resolvedFragments(node, context));
     return;
   }
-  if (node.type === "MemberExpression") {
-    // A dynamic lookup can select any value in a local class table. Resolve the
-    // entire object so no palette entry can hide behind `classes[current]`.
-    collectStaticClassFragments(node.object, fragments, context, seen, includeObjectKeys);
-    return;
-  }
-  if (
-    node.type === "TSAsExpression" ||
-    node.type === "TSSatisfiesExpression" ||
-    node.type === "TSNonNullExpression" ||
-    node.type === "TypeCastExpression"
-  ) {
-    collectStaticClassFragments(node.expression, fragments, context, seen, includeObjectKeys);
-  }
-}
 
-function staticPropertyName(property) {
-  if (property.key.type === "Identifier" && !property.computed) return property.key.name;
-  if (property.key.type === "Literal" && typeof property.key.value === "string") {
-    return property.key.value;
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "parent" || key === "loc" || key === "range") continue;
+    // A cva variant map's keys name variants, not classes.
+    if (skipPropertyKeys && key === "key" && node.type === "Property" && !node.computed) continue;
+    if (Array.isArray(value)) {
+      for (const child of value) literalFragments(child, fragments, { skipPropertyKeys, context });
+    } else if (value && typeof value === "object") {
+      literalFragments(value, fragments, { skipPropertyKeys, context });
+    }
   }
-  return undefined;
 }
 
-function collectStaticSpreadClassFragments(node, fragments, context, seen = new Set()) {
-  if (!node || seen.has(node)) return;
-  seen.add(node);
+function utilities(node, { skipPropertyKeys = false, context } = {}) {
+  const fragments = [];
+  literalFragments(node, fragments, { skipPropertyKeys, context });
+  return fragments.flatMap((fragment) => fragment.split(/\s+/).filter(Boolean));
+}
 
-  if (node.type === "Identifier") {
-    collectStaticSpreadClassFragments(variableInitializer(node, context), fragments, context, seen);
-    return;
-  }
-  if (node.type === "ObjectExpression") {
-    for (const property of node.properties) {
-      if (property.type === "SpreadElement") {
-        collectStaticSpreadClassFragments(property.argument, fragments, context, seen);
-        continue;
-      }
-      if (staticPropertyName(property) === "className") {
-        collectStaticClassFragments(property.value, fragments, context, seen);
-      }
-    }
-    return;
-  }
-  if (node.type === "ConditionalExpression") {
-    collectStaticSpreadClassFragments(node.consequent, fragments, context, seen);
-    collectStaticSpreadClassFragments(node.alternate, fragments, context, seen);
-    return;
-  }
-  if (node.type === "LogicalExpression") {
-    collectStaticSpreadClassFragments(node.left, fragments, context, seen);
-    collectStaticSpreadClassFragments(node.right, fragments, context, seen);
-    return;
-  }
-  if (
-    node.type === "TSAsExpression" ||
-    node.type === "TSSatisfiesExpression" ||
-    node.type === "TSNonNullExpression" ||
-    node.type === "TypeCastExpression"
-  ) {
-    collectStaticSpreadClassFragments(node.expression, fragments, context, seen);
-  }
+/**
+ * Every class utility written inside one node, wherever it sits. The reader for
+ * a rule whose surface is not a JSX element — a `cn()`/`cva()` call assigned to
+ * a `className` property, or a bare class string in a props object — which is
+ * where this repository's composed class lists actually live.
+ *
+ * Pass `skipPropertyKeys` for a cva call, whose variant-map keys name variants
+ * rather than classes.
+ */
+export function nodeClassUtilities(node, context, { skipPropertyKeys = false } = {}) {
+  return utilities(node, { skipPropertyKeys, context });
 }
 
+/**
+ * The class utilities written in one `className` JSX attribute. Pass `context`
+ * to take the one hop; without it the reader stays literal-only.
+ */
 export function classUtilities(attribute, context) {
   if (attribute?.type !== "JSXAttribute" || attribute.name.name !== "className") return [];
-  return staticClassUtilities(attribute.value, context);
+  return utilities(attribute.value, { context });
 }
 
-export function staticStringFragments(node, context) {
-  const fragments = [];
-  collectStaticClassFragments(node, fragments, context);
-  return fragments;
+/** The `className` a spread object carries — its own key only, not its other values. */
+function spreadClassUtilities(attribute, context) {
+  if (attribute.argument.type !== "Identifier") return [];
+  const initializer = constInitializer(attribute.argument, context);
+  if (initializer?.type !== "ObjectExpression") return [];
+  for (const property of initializer.properties) {
+    if (property.type !== "Property" || property.computed) continue;
+    const name = property.key.type === "Identifier" ? property.key.name : property.key.value;
+    if (name !== "className" && name !== "class") continue;
+    if (property.value.type !== "Literal" || typeof property.value.value !== "string") continue;
+    return property.value.value.split(/\s+/).filter(Boolean);
+  }
+  return [];
 }
 
-function staticClassUtilities(node, context) {
-  return staticStringFragments(node, context).flatMap((fragment) =>
-    fragment.split(/\s+/).filter(Boolean),
+/** The class utilities written across every attribute of one element, spreads included. */
+export function openingElementClassUtilities(node, context) {
+  return node.attributes.flatMap((attribute) =>
+    attribute.type === "JSXSpreadAttribute"
+      ? spreadClassUtilities(attribute, context)
+      : classUtilities(attribute, context),
   );
 }
 
-function staticValueClassUtilities(node, context) {
-  const fragments = [];
-  collectStaticClassFragments(node, fragments, context, new Set(), false);
-  return fragments.flatMap((fragment) => fragment.split(/\s+/).filter(Boolean));
-}
-
+/**
+ * `className` attributes plus `cva()` calls — the two places a design-token
+ * utility is written. The token rules run over both because a cva variant map
+ * is where a component's class strings actually live.
+ */
 export function tokenUtilityVisitors(context, onUtility) {
   const cvaNames = new Set();
 
-  function visitUtilities(node, utilities) {
-    for (const utility of utilities) onUtility(node, utility);
-  }
-
   return {
     ImportDeclaration(node) {
       if (node.source.value !== "class-variance-authority") return;
@@ -209,23 +186,32 @@ export function tokenUtilityVisitors(context, onUtility) {
       }
     },
     JSXAttribute(node) {
-      visitUtilities(node, classUtilities(node, context));
+      for (const utility of classUtilities(node, context)) onUtility(node, utility);
     },
     CallExpression(node) {
       if (node.callee.type !== "Identifier" || !cvaNames.has(node.callee.name)) return;
-      visitUtilities(node, staticValueClassUtilities(node, context));
+      for (const utility of utilities(node, { skipPropertyKeys: true, context })) {
+        onUtility(node, utility);
+      }
     },
   };
 }
 
-export function openingElementClassUtilities(node, context) {
-  const fragments = [];
-  for (const attribute of node.attributes) {
-    if (attribute.type === "JSXAttribute" && attribute.name.name === "className") {
-      fragments.push(...staticStringFragments(attribute.value, context));
-    } else if (attribute.type === "JSXSpreadAttribute") {
-      collectStaticSpreadClassFragments(attribute.argument, fragments, context);
-    }
-  }
-  return fragments.flatMap((fragment) => fragment.split(/\s+/).filter(Boolean));
+/*
+ * Package ownership as a per-rule option (#821, #822). `@nadicodeai/ui`'s own
+ * source is the place the primitives are BUILT, so a rule that polices what
+ * callers do to a primitive has nothing to say there — that is the "exempt"
+ * default. A rule whose invariant holds inside the package too selects "lint".
+ */
+const PACKAGE_PRIMITIVE_PATH = "packages/ui/src/";
+
+export const packageOwnedPrimitivesSchema = {
+  type: "object",
+  properties: { packageOwnedPrimitives: { enum: ["exempt", "lint"] } },
+  additionalProperties: false,
+};
+
+export function skipsPackageOwnedPrimitive(context) {
+  if (context.options?.[0]?.packageOwnedPrimitives === "lint") return false;
+  return context.filename.replaceAll("\\", "/").includes(PACKAGE_PRIMITIVE_PATH);
 }

package/dist/eslint/rules/no-app-feature-component.js

@@ -0,0 +1,100 @@
+/*
+ * `@nadicodeai/ui` ships standard components. An operator login, a portal
+ * activation screen, a customer-credential panel — those are use cases, and a
+ * use case in the package is a screen two consumers can never both want. The
+ * boundary is named in the app's vocabulary, so the rule reads names: the
+ * module's own file name and everything it exports.
+ *
+ * Standard tool checked (ADR 0057 tier 2): core `no-restricted-syntax` matches
+ * an exported identifier against a regex through esquery, but it is given one
+ * node at a time and never the file that node is in — and a module called
+ * `activation.tsx` exporting `Banner` is the case the file name is there to
+ * catch. `context.filename` is why this is a rule rather than a selector list.
+ *
+ * The vocabulary itself is configuration, not code: the banned words live in the
+ * workspace's eslint config where the package boundary is drawn, and this file
+ * holds only the matching. Replaces the @nadicodeai/ui no-app-feature-components
+ * scanner (#822), which built a TypeScript AST over the package's components to
+ * ask the same question.
+ */
+
+/** `OperatorLoginCard` and `operator-login.tsx` both normalise to `operator-login`. */
+function normalizeName(value) {
+  return value
+    .replace(/\.[jt]sx?$/, "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/[\s_]+/g, "-")
+    .toLowerCase();
+}
+
+/** The declared names one `export` statement introduces. */
+function exportedNames(node) {
+  if (!node.declaration) {
+    return node.specifiers.map((specifier) => specifier.exported.name ?? specifier.exported.value);
+  }
+  const declaration = node.declaration;
+  if (declaration.type === "VariableDeclaration") {
+    return declaration.declarations
+      .filter((declarator) => declarator.id.type === "Identifier")
+      .map((declarator) => declarator.id.name);
+  }
+  return declaration.id ? [declaration.id.name] : [];
+}
+
+export const noAppFeatureComponent = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow app-owned feature and use-case names in a shared component package",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          names: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: { feature: { type: "string" }, pattern: { type: "string" } },
+              required: ["feature", "pattern"],
+              additionalProperties: false,
+            },
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      appFeature:
+        "{{what}} names the {{feature}} use case. This package ships standard components; compose an app feature inside the consuming app.",
+    },
+  },
+  create(context) {
+    const names = (context.options?.[0]?.names ?? []).map(({ feature, pattern }) => ({
+      feature,
+      pattern: new RegExp(pattern),
+    }));
+    if (names.length === 0) return {};
+
+    const feature = (candidate) =>
+      names.find(({ pattern }) => pattern.test(normalizeName(candidate)))?.feature;
+
+    const report = (node, candidate, what) => {
+      const matched = feature(candidate);
+      if (matched)
+        context.report({ node, messageId: "appFeature", data: { what, feature: matched } });
+    };
+
+    return {
+      Program(node) {
+        const file = context.filename.replaceAll("\\", "/").split("/").at(-1) ?? "";
+        report(node, file, `The module name "${file}"`);
+      },
+      ExportNamedDeclaration(node) {
+        for (const name of exportedNames(node)) {
+          report(node, name, `The export "${name}"`);
+        }
+      },
+    };
+  },
+};

package/dist/eslint/rules/no-deprecated-zod-api.js

@@ -1,9 +1,40 @@
+/*
+ * Legacy Zod 3 APIs, in two sets that are enforced from two different places.
+ *
+ * UNANNOTATED — the four Zod itself leaves without a `@deprecated` tag.
+ * Verified against zod 4.4.3's declarations: `nativeEnum` and `promise` carry
+ * only prose, `.strict()` and `.strip()` carry only a "consider…" hint. No tag
+ * means no type-aware rule can ever fire on them, so they are this rule's own
+ * policy and are reported in every workspace.
+ *
+ * ANNOTATED — the rest, which Zod does tag `@deprecated`.
+ * `@typescript-eslint/no-deprecated` reports those with the library's own
+ * replacement text, but only where lint parses with type information. In this
+ * repository that is `@nadicodeai/ui` alone: switching the Portal on measured
+ * 10.4s → 25.8s per lint run and surfaced 15 unrelated findings (React's
+ * `FormEvent`, vitest's `toThrowError`), so typed lint stays ui-only (#821).
+ * The Portal and the website are where this repository writes most of its Zod,
+ * so the names stay listed here for them — a second copy of an upstream
+ * annotation, kept deliberately because the alternative is no coverage at all
+ * in two of three workspaces (#822).
+ *
+ * The split is a rule option: `upstreamAnnotated: "report"` (default) names
+ * them, `"defer"` leaves them to the type-aware rule. `@nadicodeai/ui` selects
+ * `"defer"` in the root config, so no file is reported twice.
+ */
 const LEGACY_FACTORIES = new Map([
   ["nativeEnum", "z.enum()"],
   ["promise", "await the value before parsing it"],
 ]);
 
 const LEGACY_METHODS = {
+  object: new Map([
+    ["strict", "z.strictObject()"],
+    ["strip", "z.object(), which strips unknown keys by default"],
+  ]),
+};
+
+const UPSTREAM_ANNOTATED_METHODS = {
   number: new Map([
     ["finite", "remove it; z.number() already rejects infinite values"],
     ["safe", ".int()"],
@@ -12,13 +43,13 @@ const LEGACY_METHODS = {
   object: new Map([
     ["merge", ".extend(other.shape)"],
     ["passthrough", "z.looseObject()"],
-    ["strict", "z.strictObject()"],
-    ["strip", "z.object(), which strips unknown keys by default"],
   ]),
-  string: new Map(
-    [
+  string: new Map([
+    ...[
       "base64",
       "base64url",
+      "cidrv4",
+      "cidrv6",
       "cuid",
       "cuid2",
       "e164",
@@ -38,14 +69,24 @@ const LEGACY_METHODS = {
       "uuidv7",
       "xid",
     ].map((name) => [name, `z.${name.startsWith("uuidv") ? "uuid" : name}()`]),
-  ),
+    ...["date", "datetime", "duration", "time"].map((name) => [name, `z.iso.${name}()`]),
+  ]),
 };
 
-for (const name of ["date", "datetime", "duration", "time"]) {
-  LEGACY_METHODS.string.set(name, `z.iso.${name}()`);
-}
-for (const name of ["cidrv4", "cidrv6"]) {
-  LEGACY_METHODS.string.set(name, `z.${name}()`);
+/** The method table a run consults: the four always, the annotated names unless deferred. */
+function legacyMethods(context) {
+  if (context.options?.[0]?.upstreamAnnotated === "defer") return LEGACY_METHODS;
+  const merged = {};
+  for (const family of new Set([
+    ...Object.keys(LEGACY_METHODS),
+    ...Object.keys(UPSTREAM_ANNOTATED_METHODS),
+  ])) {
+    merged[family] = new Map([
+      ...(UPSTREAM_ANNOTATED_METHODS[family] ?? []),
+      ...(LEGACY_METHODS[family] ?? []),
+    ]);
+  }
+  return merged;
 }
 
 function memberName(node) {
@@ -62,17 +103,24 @@ export const noDeprecatedZodApi = {
   meta: {
     type: "problem",
     docs: {
-      description: "Disallow deprecated and legacy Zod APIs when a Zod 4 replacement exists",
+      description: "Disallow the Zod 3 APIs that Zod 4 replaced without marking them @deprecated",
     },
-    schema: [],
+    schema: [
+      {
+        type: "object",
+        properties: { upstreamAnnotated: { enum: ["report", "defer"] } },
+        additionalProperties: false,
+      },
+    ],
     messages: {
-      legacyFactory: "{{api}} is deprecated in Zod 4; use {{replacement}}.",
-      legacyMethod: "{{api}} is deprecated or legacy in Zod 4; use {{replacement}}.",
+      legacyFactory: "{{api}} is legacy in Zod 4; use {{replacement}}.",
+      legacyMethod: "{{api}} is legacy in Zod 4; use {{replacement}}.",
     },
   },
 
   create(context) {
     const sourceCode = context.sourceCode;
+    const methods = legacyMethods(context);
     const zodBindings = new Set();
 
     function isZodBinding(identifier) {
@@ -142,7 +190,7 @@ export const noDeprecatedZodApi = {
 
         const factory = rootFactory(node.callee.object);
         const family = factory === "strictObject" || factory === "looseObject" ? "object" : factory;
-        const replacement = LEGACY_METHODS[family]?.get(method);
+        const replacement = methods[family]?.get(method);
         if (replacement) {
           context.report({
             node: node.callee.property,