@ethisyscore/eslint-plugin-coreconnect 1.134.1 → 1.134.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ethisyscore/eslint-plugin-coreconnect",
-  "version": "1.134.1",
+  "version": "1.134.3",
   "description": "ESLint rules enforcing EthisysCore plugin frontend conventions. Published so a new rule reaches every plugin on a version bump, rather than being copied into each scaffold and drifting.",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -1,3 +1,4 @@
+import noBareDatePicker from "./rules/no-bare-date-picker.js";
 import noHardcodedColors from "./rules/no-hardcoded-colors.js";
 import noInlineObjectType from "./rules/no-inline-object-type.js";
 import noInlineStringUnion from "./rules/no-inline-string-union.js";
@@ -14,6 +15,7 @@ import noSecondMarkdownRenderer, {
 } from "./rules/no-second-markdown-renderer.js";
 
 const rules = {
+  "no-bare-date-picker": noBareDatePicker,
   "no-hardcoded-colors": noHardcodedColors,
   "no-inline-object-type": noInlineObjectType,
   "no-inline-string-union": noInlineStringUnion,

package/src/rules/no-bare-date-picker.js

@@ -0,0 +1,253 @@
+/**
+ * Disallow rendering a MUI X date picker directly instead of the shared `DateInput`.
+ *
+ * The companion to `no-local-date-input`, and the gap it left. That rule fires on a DECLARATION -
+ * a local `DateInput` / `*DatePicker` component - so it stops a seventh copy of the field being
+ * written. It says nothing about a view that skips the field entirely and renders
+ * `<LocalizationProvider dateAdapter={AdapterDayjs}><DatePicker ... /></LocalizationProvider>`
+ * inline, and that is the shape that shipped the defect this rule exists for.
+ *
+ * A bare picker carries neither of the things the shared field is for:
+ *
+ *   - no `format`, so the editable mask ignores the organisation's configured date format
+ *     (`getOrgDateInputFormat`, stamped per surface by `useOrgFormatSync`);
+ *   - and, in every instance found, no `adapterLocale` either, so MUI X expands dayjs's global
+ *     `en` locale and renders US MM/DD/YYYY. For a day <= 12 that is a plausible-looking WRONG
+ *     date to a UK reader, which is why it survives review.
+ *
+ * Measured on origin/develop at 1.131.0, after AB#5140 had "fixed" the order app-wide through the
+ * shared field: nine pickers across hr (4), finance, projects and timesheets still rendered
+ * month-first, because each imported `DatePicker` from `@mui/x-date-pickers` and none of them
+ * declared a component this package's other rule could see. The skills already said "replace any
+ * raw DatePicker that carries no format="; prose did not hold the line, so this does.
+ *
+ * WHAT IS REPORTED. A value import (or re-export) of a date-bearing picker or field - `DatePicker`,
+ * `DateTimePicker`, their `Desktop` / `Mobile` / `Static` variants, `DateField`, `DateTimeField` -
+ * from `@mui/x-date-pickers` or `@mui/x-date-pickers-pro`, root or sub-path. A namespace, default
+ * or dynamic import of a package ROOT names no export at the import, so it is judged where it is
+ * read: `<Pickers.DatePicker />`, `Pickers.DateTimePicker`, `const { DatePicker } = await import(...)`.
+ *
+ * WHAT IS NOT, and why:
+ *   - `TimePicker` and friends: there is no shared time field, and a time carries no day/month
+ *     order to get wrong. Banning it would leave the author nothing to use instead.
+ *   - `LocalizationProvider` / `AdapterDayjs`: needed by a TimePicker, and harmless on their own.
+ *   - Range pickers (`DateRangePicker`, pro): no shared equivalent exists yet either.
+ *   - Type-only imports (`import type { DatePickerProps }`): nothing renders.
+ *   - A computed specifier (`import(name)`): cannot be resolved statically; reporting it is a guess.
+ *   - A ROOT binding that only ever reads `TimePicker` (or anything else not date-bearing): the
+ *     import itself is not reported, only a date picker read from it.
+ *
+ * The SDK's own `plugin-ui` DateInput imports `DatePicker` - it is the one sanctioned wrapper - and
+ * is not linted with this config. A consumer that genuinely needs a raw picker turns the rule off
+ * for that file after the `recommended` spread, where the exemption is visible.
+ *
+ * @type {import("eslint").Rule.RuleModule}
+ */
+
+/** The picker packages. The pro package re-exports every community picker under the same names. */
+const PICKER_PACKAGE = /^@mui\/x-date-pickers(-pro)?(\/(?<subpath>[^/]+))?$/;
+
+/**
+ * Date-bearing pickers and fields. Anchored both ends so `DatePickerProps`, `DateRangePicker`,
+ * `TimePicker` and `DateCalendar` stay out of it.
+ */
+const DATE_PICKER_NAME = /^(Desktop|Mobile|Static)?Date(Time)?(Picker|Field)$/;
+
+const CANONICAL_SOURCE = "@ethisyscore/plugin-ui/components/date";
+
+/**
+ * The sub-path of a picker package import, or null when the source is not a picker package.
+ * Returns "" for the package root.
+ *
+ * @param {string} source
+ */
+function pickerSubpath(source) {
+  const match = PICKER_PACKAGE.exec(source);
+  if (!match) return null;
+  return match.groups?.subpath ?? "";
+}
+
+/** `import type {...}` / `export type {...}` or `{ type X }` - nothing is rendered. */
+function isTypeOnly(node) {
+  return node.importKind === "type" || node.exportKind === "type";
+}
+
+/** The name an import or export specifier takes FROM the module. */
+function importedName(specifier) {
+  const imported = specifier.type === "ExportSpecifier" ? specifier.local : specifier.imported;
+  if (!imported) return null;
+  return imported.type === "Identifier" ? imported.name : imported.value;
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow rendering a MUI X date picker directly - import DateInput from @ethisyscore/plugin-ui/components/date",
+    },
+    messages: {
+      noBareDatePicker:
+        "'{{name}}' from '{{source}}' renders a date field outside the shared DateInput, so its mask ignores the organisation's date format and falls back to MUI X's en-US MM/DD/YYYY. Import { DateInput } from '" +
+        CANONICAL_SOURCE +
+        "' instead: it takes and emits ISO YYYY-MM-DD strings, with min/max, label, helperText and error.",
+    },
+    schema: [],
+  },
+  create(context) {
+    const report = (node, name, source) =>
+      context.report({ node, messageId: "noBareDatePicker", data: { name, source } });
+
+    /**
+     * Named specifiers are judged by the name they take from the module. A default or namespace
+     * specifier has no such name, so it is judged by the sub-path it came from: `import * as P from
+     * "@mui/x-date-pickers/DatePicker"` is the picker, the same import of the root is not knowable.
+     */
+    const checkSpecifiers = (node, source, subpath) => {
+      if (isTypeOnly(node)) return;
+
+      for (const specifier of node.specifiers ?? []) {
+        if (isTypeOnly(specifier)) continue;
+
+        const named = specifier.type === "ImportSpecifier" || specifier.type === "ExportSpecifier";
+        // `{ default as X }` takes the sub-path's default export, so it is the sub-path that names it.
+        const taken = named ? importedName(specifier) : null;
+        const name = taken && taken !== "default" ? taken : subpath;
+        if (name && DATE_PICKER_NAME.test(name)) {
+          report(specifier, name, source);
+        }
+      }
+    };
+
+    const literalSource = (node) =>
+      node.source && node.source.type === "Literal" && typeof node.source.value === "string"
+        ? node.source.value
+        : null;
+
+    /**
+     * The DEFINING nodes of bindings to a picker package ROOT as a whole - the `import * as P` /
+     * default specifier, or the `const P = await import(...)` declarator - mapped to the source.
+     * Which export such a binding renders is only visible where it is read (`<P.DatePicker />`,
+     * `P.DateTimePicker`), so it is judged there, after resolving the read through ESLint's scope
+     * manager: a same-named parameter or local that shadows the import is a different variable and
+     * must not turn a correct file red at "error".
+     */
+    const rootBindings = new Map();
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+
+    /** The picker-root source a read of `identifier` resolves to, or undefined. */
+    const resolveRootBinding = (identifier) => {
+      for (let scope = sourceCode.getScope(identifier); scope; scope = scope.upper) {
+        const variable = scope.set.get(identifier.name);
+        if (variable) {
+          const def = variable.defs[0];
+          return def ? rootBindings.get(def.node) : undefined;
+        }
+      }
+      return undefined;
+    };
+
+    /** `await import("x")` and `import("x")` alike: the source when it is a picker package root. */
+    const rootImportSource = (init) => {
+      const expression = init && init.type === "AwaitExpression" ? init.argument : init;
+      if (!expression || expression.type !== "ImportExpression") return null;
+      const source = literalSource(expression);
+      return source !== null && pickerSubpath(source) === "" ? source : null;
+    };
+
+    /** The static name of `obj.name` / `obj["name"]`, or null when it is computed. */
+    const memberName = (property, computed) => {
+      if (!computed && (property.type === "Identifier" || property.type === "JSXIdentifier")) return property.name;
+      if (computed && property.type === "Literal" && typeof property.value === "string") return property.value;
+      return null;
+    };
+
+    const checkMember = (node, source, property, computed) => {
+      const name = source === undefined || source === null ? null : memberName(property, computed);
+      if (name && DATE_PICKER_NAME.test(name)) {
+        report(node, name, source);
+      }
+    };
+
+    return {
+      ImportDeclaration(node) {
+        const source = literalSource(node);
+        const subpath = source === null ? null : pickerSubpath(source);
+        if (subpath === null) return;
+        checkSpecifiers(node, source, subpath);
+
+        if (subpath !== "" || isTypeOnly(node)) return;
+        for (const specifier of node.specifiers ?? []) {
+          if (specifier.type === "ImportNamespaceSpecifier" || specifier.type === "ImportDefaultSpecifier") {
+            rootBindings.set(specifier, source);
+          }
+        }
+      },
+      // `const { DatePicker } = await import("@mui/x-date-pickers")` - or `= P` for an existing root
+      // binding - names the picker at the binding; `const Q = await import(...)` / `const Q = P`
+      // defers the judgement to where `Q.DatePicker` is read.
+      VariableDeclarator(node) {
+        const source =
+          rootImportSource(node.init) ??
+          (node.init && node.init.type === "Identifier" ? resolveRootBinding(node.init) ?? null : null);
+        if (source === null) return;
+
+        if (node.id.type === "Identifier") {
+          rootBindings.set(node, source);
+          return;
+        }
+        if (node.id.type !== "ObjectPattern") return;
+        for (const property of node.id.properties) {
+          if (property.type !== "Property") continue;
+          const name = memberName(property.key, property.computed);
+          if (name && DATE_PICKER_NAME.test(name)) {
+            report(property, name, source);
+          }
+        }
+      },
+      // `P.DatePicker` / `P["DatePicker"]` on a root binding, and `(await import(root)).DatePicker`
+      // read straight off the import with no binding in between.
+      MemberExpression(node) {
+        if (node.object.type === "Identifier") {
+          checkMember(node, resolveRootBinding(node.object), node.property, node.computed);
+        } else {
+          checkMember(node, rootImportSource(node.object), node.property, node.computed);
+        }
+      },
+      // `<P.DatePicker />` on a root binding.
+      JSXMemberExpression(node) {
+        if (node.object.type === "JSXIdentifier") {
+          checkMember(node, resolveRootBinding(node.object), node.property, false);
+        }
+      },
+      // `export { DatePicker } from "@mui/x-date-pickers"` - a local re-export barrel is the same
+      // bare picker one file further away.
+      ExportNamedDeclaration(node) {
+        const source = literalSource(node);
+        const subpath = source === null ? null : pickerSubpath(source);
+        if (subpath === null) return;
+        checkSpecifiers(node, source, subpath);
+      },
+      // `export * from "@mui/x-date-pickers"` re-exports every picker at once.
+      ExportAllDeclaration(node) {
+        const source = literalSource(node);
+        const subpath = source === null ? null : pickerSubpath(source);
+        if (subpath === null || isTypeOnly(node)) return;
+        if (subpath === "" || DATE_PICKER_NAME.test(subpath)) {
+          report(node.source, subpath || "*", source);
+        }
+      },
+      // `await import("@mui/x-date-pickers/DatePicker")`. Espree parses this as an
+      // ImportExpression, not a CallExpression, which is the form a call site reaches for to dodge a
+      // static-import rule. A sub-path that names a picker is reported here; a ROOT import is judged
+      // by what its binding reads (VariableDeclarator / MemberExpression above).
+      ImportExpression(node) {
+        const source = literalSource(node);
+        const subpath = source === null ? null : pickerSubpath(source);
+        if (subpath && DATE_PICKER_NAME.test(subpath)) {
+          report(node.source, subpath, source);
+        }
+      },
+    };
+  },
+};