@ethisyscore/eslint-plugin-coreconnect 1.64.0

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@ethisyscore/eslint-plugin-coreconnect",
+  "version": "1.64.0",
+  "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",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "license": "Apache-2.0",
+  "author": "Ethisys",
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "ethisyscore",
+    "plugin",
+    "conventions"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "lint:goldens": "node tools/lint-goldens.mjs"
+  },
+  "peerDependencies": {
+    "eslint": ">=9.0.0"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.67.0",
+    "@typescript-eslint/parser": "^8.67.0",
+    "eslint": "^9.39.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,56 @@
+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";
+import noLocalDataGrid from "./rules/no-local-data-grid.js";
+import noLocalDateInput from "./rules/no-local-date-input.js";
+import noLocalEmptyState from "./rules/no-local-empty-state.js";
+import noLocalSearchInput from "./rules/no-local-search-input.js";
+import noParamInNavPath from "./rules/no-param-in-nav-path.js";
+
+const rules = {
+  "no-hardcoded-colors": noHardcodedColors,
+  "no-inline-object-type": noInlineObjectType,
+  "no-inline-string-union": noInlineStringUnion,
+  "no-local-data-grid": noLocalDataGrid,
+  "no-local-date-input": noLocalDateInput,
+  "no-local-empty-state": noLocalEmptyState,
+  "no-local-search-input": noLocalSearchInput,
+  "no-param-in-nav-path": noParamInNavPath,
+};
+
+/**
+ * EthisysCore plugin frontend conventions as ESLint rules.
+ *
+ * Published as a package rather than copied into each scaffold. A rule vendored into the template
+ * can never reach a plugin that was generated before it existed, and seven copies of a rule drift.
+ * This way a new rule arrives on a version bump.
+ *
+ * A generated plugin extends `configs.recommended` rather than listing rules. That distinction is
+ * the whole delivery mechanism: an explicit rule list would freeze the plugin at the rules that
+ * existed on the day it was scaffolded, so a rule added later would ship and enforce nothing. A
+ * plugin that needs to opt out of one rule turns that rule off after the spread, which leaves the
+ * opt-out visible in its own config instead of hidden as an absence.
+ */
+const plugin = {
+  // No `version` in meta on purpose: the publish pipeline stamps the release version onto
+  // package.json, so a hardcoded value here would be wrong from the first release onward. ESLint
+  // treats meta.version as optional.
+  meta: {
+    name: "@ethisyscore/eslint-plugin-coreconnect",
+  },
+  rules,
+  configs: {},
+};
+
+/**
+ * Every rule at error severity. A convention worth a rule is worth failing the build for; a rule
+ * that should only warn belongs in review instead, per the enforcement audit's classification.
+ */
+plugin.configs.recommended = {
+  name: "coreconnect/recommended",
+  plugins: { coreconnect: plugin },
+  rules: Object.fromEntries(Object.keys(rules).map((name) => [`coreconnect/${name}`, "error"])),
+};
+
+export default plugin;
+export { rules };

package/src/rules/componentDeclarations.js

@@ -0,0 +1,102 @@
+/**
+ * Shared machinery for the "don't re-declare a promoted primitive" rules.
+ *
+ * The three rules that back a `plugin-ui` promotion ask the same question - "is this a local
+ * declaration of a component whose name matches X?" - so the question is answered once here. Three
+ * copies of this predicate would have been an unusually poor look for rules whose entire purpose is
+ * to stop code being copied three times.
+ */
+
+/** Wrappers a component declaration is commonly built from. */
+const COMPONENT_WRAPPERS = new Set(["memo", "forwardRef", "observer"]);
+
+/**
+ * A hook, not a component.
+ *
+ * These rules match on a name SUFFIX, so without this guard `useEmptyState` trips the empty-state
+ * rule and `useDatePicker` trips the date rule - both false positives on code that is not a
+ * component at all. React's own convention (`use` + an uppercase letter) is what makes this safe to
+ * detect by name.
+ *
+ * @param {string} name
+ */
+export function isHookName(name) {
+  return /^use[A-Z]/.test(name);
+}
+
+/**
+ * Is this initializer a component definition rather than a string, config object or hook result?
+ *
+ * @param {import("estree").Expression | null | undefined} init
+ */
+export function looksLikeComponent(init) {
+  if (!init) {
+    return false;
+  }
+
+  if (init.type === "ArrowFunctionExpression" || init.type === "FunctionExpression") {
+    return true;
+  }
+
+  if (init.type === "CallExpression") {
+    const callee = init.callee;
+    if (callee.type === "Identifier" && COMPONENT_WRAPPERS.has(callee.name)) {
+      return true;
+    }
+
+    // React.memo(...) / React.forwardRef(...) - the shape the promoted files themselves used.
+    if (
+      callee.type === "MemberExpression" &&
+      callee.property.type === "Identifier" &&
+      COMPONENT_WRAPPERS.has(callee.property.name)
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Builds a rule that reports a locally-declared component whose name matches `pattern`.
+ *
+ * @param {object} options
+ * @param {RegExp} options.pattern Name pattern, anchored at the end by the caller.
+ * @param {string} options.messageId
+ * @param {string} options.description
+ * @param {string} options.message
+ * @returns {import("eslint").Rule.RuleModule}
+ */
+export function createNoLocalComponentRule({ pattern, messageId, description, message }) {
+  return {
+    meta: {
+      type: "problem",
+      docs: { description },
+      messages: { [messageId]: message },
+      schema: [],
+    },
+    create(context) {
+      const check = (idNode) => {
+        if (!idNode || idNode.type !== "Identifier") {
+          return;
+        }
+
+        if (isHookName(idNode.name) || !pattern.test(idNode.name)) {
+          return;
+        }
+
+        context.report({ node: idNode, messageId, data: { name: idNode.name } });
+      };
+
+      return {
+        FunctionDeclaration: (node) => check(node.id),
+        ClassDeclaration: (node) => check(node.id),
+        VariableDeclarator: (node) => {
+          if (looksLikeComponent(node.init)) {
+            check(node.id);
+          }
+        },
+      };
+    },
+  };
+}

package/src/rules/no-hardcoded-colors.js

@@ -0,0 +1,37 @@
+/**
+ * Disallow hardcoded colour values.
+ *
+ * A hardcoded colour renders fine on the author's machine, looks subtly wrong in the other theme,
+ * and never follows the design system when it changes. Six files in a shipped plugin carry them
+ * today, and this rule existed in the scaffold template the whole time without anything running it.
+ *
+ * @type {import("eslint").Rule.RuleModule}
+ */
+const COLOR_REGEX = /^#(?:[0-9a-fA-F]{3}){1,2}(?:[0-9a-fA-F]{2})?$|^rgba?\(|^hsla?\(/;
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Disallow hardcoded color values - use --cc-* CSS variables or cc-* Tailwind classes",
+    },
+    messages: {
+      noHardcodedColor:
+        "Detected hardcoded color '{{value}}'. Use 'var(--cc-*)' or 'cc-*' Tailwind classes so the value follows the theme and dark mode.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      Literal(node) {
+        if (typeof node.value !== "string") {
+          return;
+        }
+        if (COLOR_REGEX.test(node.value.trim())) {
+          context.report({ node, messageId: "noHardcodedColor", data: { value: node.value } });
+        }
+      },
+    };
+  },
+};

package/src/rules/no-inline-object-type.js

@@ -0,0 +1,108 @@
+/**
+ * Disallow an inline object type in a parameter, a return type, or an exported variable annotation.
+ *
+ * One of the four things a lead reports as most of their review comments. An inline `{ id: string;
+ * name: string }` cannot be referenced, imported, or found by name, so the next person who needs the
+ * same shape writes it again slightly differently - and the two drift with nothing to notice. A
+ * named `interface` or `type` costs one line and makes the shape a thing you can point at.
+ *
+ * Scoped to three positions on purpose. A blanket ban on `TSTypeLiteral` would flag legitimate
+ * inline shapes in generic arguments (`useState<{ open: boolean }>`), mapped types and `Record`
+ * values, which would make the rule noise and get it switched off.
+ *
+ * @type {import("eslint").Rule.RuleModule}
+ */
+
+const FUNCTION_LIKE = new Set([
+  "FunctionDeclaration",
+  "FunctionExpression",
+  "ArrowFunctionExpression",
+  "TSDeclareFunction",
+  "TSFunctionType",
+  "MethodDefinition",
+  "TSMethodSignature",
+]);
+
+const PARAMETER_HOLDERS = new Set([
+  "Identifier",
+  "ObjectPattern",
+  "ArrayPattern",
+  "RestElement",
+  "AssignmentPattern",
+]);
+
+/** Is this node exported, directly or via a containing declaration? */
+function isExported(node) {
+  for (let current = node; current; current = current.parent) {
+    if (
+      current.type === "ExportNamedDeclaration" ||
+      current.type === "ExportDefaultDeclaration"
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Classifies where a type literal sits, or returns null when the position is not one this rule
+ * governs.
+ */
+function positionOf(typeLiteral) {
+  const annotation = typeLiteral.parent;
+  if (!annotation || annotation.type !== "TSTypeAnnotation") {
+    return null;
+  }
+
+  const holder = annotation.parent;
+  if (!holder) {
+    return null;
+  }
+
+  // Return type: the annotation hangs directly off the function.
+  if (FUNCTION_LIKE.has(holder.type) && holder.returnType === annotation) {
+    return "return type";
+  }
+
+  // Parameter: the annotation hangs off a binding that the function lists as a parameter.
+  if (PARAMETER_HOLDERS.has(holder.type)) {
+    const owner = holder.parent;
+    if (owner && FUNCTION_LIKE.has(owner.type) && (owner.params ?? []).includes(holder)) {
+      return "parameter";
+    }
+
+    // An exported `const x: { ... } = ...` - the same unnameable shape, and exported, so other
+    // modules end up re-describing it.
+    if (owner && owner.type === "VariableDeclarator" && owner.id === holder && isExported(owner)) {
+      return "exported variable";
+    }
+  }
+
+  return null;
+}
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Disallow inline object types in parameters, return types and exported variable annotations - name the type",
+    },
+    messages: {
+      noInlineObjectType:
+        "Inline object type in a {{position}}. Declare a named `interface` or `type` instead: an inline shape cannot be imported or found by name, so the next person who needs it writes their own slightly different copy.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      TSTypeLiteral(node) {
+        const position = positionOf(node);
+        if (position) {
+          context.report({ node, messageId: "noInlineObjectType", data: { position } });
+        }
+      },
+    };
+  },
+};

package/src/rules/no-inline-string-union.js

@@ -0,0 +1,78 @@
+/**
+ * Disallow an inline union of three or more string literals.
+ *
+ * `"draft" | "sent" | "bounced" | "opened"` written inline is a domain vocabulary with no name, so
+ * it gets restated at every boundary it crosses - a prop, a query parameter, a switch - and the
+ * copies fall out of step one value at a time. Naming it once means adding a value is a single edit
+ * the compiler then propagates.
+ *
+ * Two-member unions are allowed. `"asc" | "desc"` needs no ceremony, and requiring a name for every
+ * pair is the kind of rule people disable wholesale.
+ *
+ * @type {import("eslint").Rule.RuleModule}
+ */
+
+const MINIMUM_MEMBERS = 3;
+
+/** A `"literal"` type node, across the parser versions that spell it differently. */
+function isStringLiteralType(node) {
+  if (node.type === "TSLiteralType") {
+    return node.literal?.type === "Literal" && typeof node.literal.value === "string";
+  }
+
+  return false;
+}
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Disallow inline unions of three or more string literals - name the union with a type alias",
+    },
+    messages: {
+      noInlineStringUnion:
+        "Inline union of {{count}} string literals. Give it a name (`type {{suggestion}} = ...`) and reference that: an unnamed vocabulary gets restated at every boundary it crosses, and the copies drift a value at a time.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      TSUnionType(node) {
+        const members = node.types ?? [];
+        if (members.length < MINIMUM_MEMBERS || !members.every(isStringLiteralType)) {
+          return;
+        }
+
+        // Already named: `type Status = "a" | "b" | "c"` is exactly what this rule asks for.
+        if (node.parent?.type === "TSTypeAliasDeclaration") {
+          return;
+        }
+
+        // A union inside a named alias's composition (e.g. `type X = ("a"|"b"|"c")[]`) is still
+        // named at the point that matters, so walking up through wrapper type nodes to find an
+        // alias keeps the rule from demanding a second name for the same thing.
+        for (let current = node.parent; current; current = current.parent) {
+          if (current.type === "TSTypeAliasDeclaration") {
+            return;
+          }
+
+          // Stop at the first node that is not part of a type expression: beyond that we are in a
+          // parameter, a return type or a variable, which is precisely what should be reported.
+          if (!current.type.startsWith("TS")) {
+            break;
+          }
+        }
+
+        context.report({
+          node,
+          messageId: "noInlineStringUnion",
+          data: {
+            count: members.length,
+            suggestion: "SomethingStatus",
+          },
+        });
+      },
+    };
+  },
+};

package/src/rules/no-local-data-grid.js

@@ -0,0 +1,30 @@
+/**
+ * Disallow a plugin declaring its own persistent data grid or its pagination helpers.
+ *
+ * The backstop to the largest promotion in this work. Measured on origin/develop across five
+ * repos: `PersistentDataGrid.tsx` 167 lines in four copies, `gridStatePersistence.ts` 174 in four,
+ * `dataGridPagination.ts` 94 in four, plus a re-export barrel - and `sales` had already drifted on
+ * four of the six files.
+ *
+ * Two fixes were riding in every copy, which is what makes duplication here expensive rather than
+ * merely untidy: the pagination helper distinguishes a page change from a page-size change (the
+ * naive version pinned the user to page 1), and the grid reads `window.location.pathname` directly
+ * so the leaf wrapper needs no Router context.
+ *
+ * Fires on a DECLARATION, never a use, so importing from `@ethisyscore/plugin-ui/components/data-grid`
+ * is exactly what the rule wants.
+ *
+ * @type {import("eslint").Rule.RuleModule}
+ */
+import { createNoLocalComponentRule } from "./componentDeclarations.js";
+
+export default createNoLocalComponentRule({
+  // Anchored at the end so `DataGridProps`, `useDataGridState` and a `ProjectsDataGridColumns`
+  // helper are left alone; the shared helper's guard keeps hooks out of it.
+  pattern: /(PersistentDataGrid|DataGridPagination|GridStatePersistence)$/,
+  messageId: "noLocalDataGrid",
+  description:
+    "Disallow a locally-declared persistent data grid - import from @ethisyscore/plugin-ui/components/data-grid",
+  message:
+    "'{{name}}' re-declares the shared data grid. Import { PersistentDataGrid, buildDataGridPaginationProps } from '@ethisyscore/plugin-ui/components/data-grid' instead: the local copies had already drifted, and each one carries the page-size fix and the no-Router-context behaviour independently.",
+});

package/src/rules/no-local-date-input.js

@@ -0,0 +1,26 @@
+/**
+ * Disallow a plugin declaring its own date or datetime input component.
+ *
+ * The backstop to a promotion. The same 134-line `date-input.tsx` sat in six of the ten plugin
+ * repos, and each copy carried two fixes that are easy to lose: `altBoundary` popper modifiers, so
+ * the calendar flips correctly inside an `overflow:hidden` MUI Dialog, and an end-of-day upper
+ * bound, without which a `datetime-local` field rejects every time on its final valid date. Six
+ * copies is six places for either to be dropped, and nothing would have noticed.
+ *
+ * Fires on a DECLARATION, never a use, so importing `DateInput` from
+ * `@ethisyscore/plugin-ui/components/ui` and rendering it is what the rule wants.
+ *
+ * @type {import("eslint").Rule.RuleModule}
+ */
+import { createNoLocalComponentRule } from "./componentDeclarations.js";
+
+export default createNoLocalComponentRule({
+  // Anchored at the end so `DateInputProps` and `DateRangeFilter` are left alone; the shared helper
+  // excludes hooks, so `useDatePicker` and `useDateInputValidation` do not match either.
+  pattern: /Date(Time)?(Input|Picker|Field)$/,
+  messageId: "noLocalDateInput",
+  description:
+    "Disallow a locally-declared date input - import DateInput from @ethisyscore/plugin-ui",
+  message:
+    "'{{name}}' looks like a local date input. Date fields must come from one implementation or the popper and bounds fixes drift: import { DateInput } from '@ethisyscore/plugin-ui/components/ui' instead. If this is genuinely something else, rename it so it does not end in Input/Picker/Field.",
+});

package/src/rules/no-local-empty-state.js

@@ -0,0 +1,25 @@
+/**
+ * Disallow a plugin declaring its own empty-state panel.
+ *
+ * The backstop to a promotion. The same 32-line `EmptyState.tsx` was identical in four of the ten
+ * plugin repos. It is small, which is exactly why it kept being rewritten - and why "empty states
+ * look different in every app" is a complaint no rule about shapes could answer. One implementation
+ * can, and this stops a fifth.
+ *
+ * Fires on a DECLARATION, never a use, so importing `EmptyState` from
+ * `@ethisyscore/plugin-ui/shared` and rendering it is what the rule wants.
+ *
+ * @type {import("eslint").Rule.RuleModule}
+ */
+import { createNoLocalComponentRule } from "./componentDeclarations.js";
+
+export default createNoLocalComponentRule({
+  // Loose enough to catch the names the same panel gets rewritten under, while the shared helper's
+  // hook guard keeps `useEmptyState` out of it.
+  pattern: /(EmptyState|NoResults|NoData|BlankSlate)$/,
+  messageId: "noLocalEmptyState",
+  description:
+    "Disallow a locally-declared empty state - import EmptyState from @ethisyscore/plugin-ui/shared",
+  message:
+    "'{{name}}' looks like a local empty state. Import { EmptyState } from '@ethisyscore/plugin-ui/shared' instead, so every app's empty state matches. It takes icon, title, description and fill; pass description=\"\" for a heading only.",
+});

package/src/rules/no-local-search-input.js

@@ -0,0 +1,27 @@
+/**
+ * Disallow a plugin declaring its own search input component.
+ *
+ * The backstop to a promotion, not a style preference. `DebouncedSearchInput` was identical in six
+ * of the ten plugin repos, and a third search field had been hand-mirrored from it in a shared
+ * toolbar - none of which a lint rule could have made consistent. The fix is one implementation,
+ * exported from `@ethisyscore/plugin-ui/components/ui`; this rule stops the next copy, since
+ * nothing else would notice.
+ *
+ * Fires on a DECLARATION, never a use, so importing the shared component and rendering
+ * `<DebouncedSearchInput />` is exactly what the rule wants.
+ *
+ * @type {import("eslint").Rule.RuleModule}
+ */
+import { createNoLocalComponentRule } from "./componentDeclarations.js";
+
+export default createNoLocalComponentRule({
+  // Anchored at the end so `SearchInputProps` and `SearchToolbar` are not matched. A toolbar that
+  // composes the shared input is a legitimate local component; a component that IS the search field
+  // is not. Hook names are excluded by the shared helper.
+  pattern: /Search(Input|Bar|Field)$/,
+  messageId: "noLocalSearchInput",
+  description:
+    "Disallow a locally-declared search input - import DebouncedSearchInput from @ethisyscore/plugin-ui",
+  message:
+    "'{{name}}' looks like a local search input. Search fields must come from one implementation or they drift: import { DebouncedSearchInput } from '@ethisyscore/plugin-ui/components/ui' instead. If this is genuinely something else, rename it so it does not end in Input/Bar/Field.",
+});

package/src/rules/no-param-in-nav-path.js

@@ -0,0 +1,58 @@
+/**
+ * Disallow a route parameter in a navigation path.
+ *
+ * A menu is rendered without a specific entity, so a path containing `:id` cannot resolve: the item
+ * either navigates nowhere or navigates to a literal colon segment. Parameterised routes belong in
+ * `pages[]`, which the host resolves with an entity in hand.
+ *
+ * Mirrors the manifest-side gate in the SDK's convention tests, so the same mistake is caught in the
+ * TypeScript menu config and in the compiled manifest. Two mechanisms, one rule, because the two
+ * declarations are hand-mirrored and drift.
+ *
+ * @type {import("eslint").Rule.RuleModule}
+ */
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Disallow :param in navigation paths - use pages[] for parameterized routes",
+    },
+    messages: {
+      noParamInNavPath:
+        "Navigation path '{{value}}' contains a dynamic parameter. A menu is rendered without an entity, so this cannot resolve. Use pages[] for parameterized routes.",
+    },
+    schema: [],
+  },
+  create(context) {
+    // A colon only means a route parameter when it OPENS a path segment: `leads/:id`, or `:id` on
+    // its own. Testing for a bare colon anywhere in the string also matches things that are not
+    // parameters at all - a protocol (`https://...`), a `mailto:`/`tel:` target, a port - and this
+    // rule reports a problem, so a false positive fails a build over a correct path.
+    const ROUTE_PARAM = /(^|\/):[A-Za-z_]/;
+
+    // The key may be written either way in an object literal, and both forms appear in real menu
+    // configs: `path:` unquoted, and `"path":` quoted (JSON pasted into a .ts file, or a config
+    // emitted by a generator). Keying only on the Identifier form silently ignored the quoted one.
+    const isPathKey = (key) =>
+      (key.type === "Identifier" && key.name === "path") ||
+      (key.type === "Literal" && key.value === "path");
+
+    return {
+      Property(node) {
+        if (
+          isPathKey(node.key) &&
+          node.value.type === "Literal" &&
+          typeof node.value.value === "string" &&
+          ROUTE_PARAM.test(node.value.value)
+        ) {
+          context.report({
+            node: node.value,
+            messageId: "noParamInNavPath",
+            data: { value: node.value.value },
+          });
+        }
+      },
+    };
+  },
+};