@yasainet/eslint 0.0.69 → 0.0.71

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yasainet/eslint",
-  "version": "0.0.69",
+  "version": "0.0.71",
   "description": "ESLint",
   "type": "module",
   "exports": {

package/src/common/imports.mjs

@@ -56,6 +56,16 @@ const LATERAL_PATTERNS = {
       message:
         "entries cannot import other feature's entries (lateral violation)",
     },
+    {
+      group: [
+        "@/features/*/services/*",
+        "@/features/*/services",
+        "!@/features/shared/services/*",
+        "!@/features/shared/services",
+      ],
+      message:
+        "entries cannot import other feature's services. Use the same feature's service (1:1) or move orchestration into the service layer. `shared/services/*` is exempt for cross-cutting side effects (notifications etc.).",
+    },
   ],
 };
 

package/src/common/local-plugins/entry-single-service-call.mjs

@@ -0,0 +1,97 @@
+/**
+ * Enforce 1:1 entry-to-service mapping for `**\/entries/*.ts` exports.
+ *
+ * Why: services are the orchestration layer (they may combine multiple queries
+ * and other features' queries). entries should be a thin wrapper that calls a
+ * single service function and normalizes the return shape into
+ * `{ data, error }`. If an entry calls more than one service, orchestration is
+ * leaking up into the entry layer.
+ *
+ * Detection rule:
+ *
+ * - For every exported async `FunctionDeclaration` in an entries file, count
+ *   `CallExpression`s whose callee is a `MemberExpression` of the form
+ *   `<binding>.<method>(...)` where `<binding>` matches the namespace import
+ *   naming convention `*Service` (e.g. `articlesServerService`,
+ *   `usersClientService`).
+ * - More than one such call inside the same exported function is an error.
+ *
+ * Exception (C-3):
+ *
+ * - Bindings starting with `shared` (e.g. `sharedDiscordService`,
+ *   `sharedResendService`) are EXCLUDED from the count. These represent
+ *   cross-cutting side-effect abstractions (Discord / Resend / Slack
+ *   notifications) that don't fit the entry-service 1:1 model and are allowed
+ *   to be invoked from entries directly.
+ *
+ * The rule reports the 2nd and later violations (the 1st call is permitted),
+ * so the fix surface is the redundant calls.
+ */
+
+const SERVICE_BINDING_REGEX = /Service$/;
+
+function isServiceCall(node) {
+  if (node?.type !== "CallExpression") return false;
+  const callee = node.callee;
+  if (callee.type !== "MemberExpression") return false;
+  const obj = callee.object;
+  if (obj.type !== "Identifier") return false;
+  if (!SERVICE_BINDING_REGEX.test(obj.name)) return false;
+  if (obj.name.startsWith("shared")) return false;
+  return true;
+}
+
+function collectServiceCalls(root) {
+  const calls = [];
+  function visit(node) {
+    if (!node || typeof node !== "object") return;
+    if (isServiceCall(node)) calls.push(node);
+    for (const key of Object.keys(node)) {
+      if (key === "parent" || key === "loc" || key === "range") continue;
+      const value = node[key];
+      if (Array.isArray(value)) {
+        for (const item of value) visit(item);
+      } else if (value && typeof value === "object" && "type" in value) {
+        visit(value);
+      }
+    }
+  }
+  visit(root);
+  return calls;
+}
+
+export const entrySingleServiceCallRule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Enforce entries call at most one (non-shared) feature service per exported function.",
+    },
+    messages: {
+      multipleServiceCalls:
+        "entry '{{ funcName }}' calls more than one feature service ({{ count }} total). entries must be a thin wrapper that calls a single service. Move orchestration into the service layer. `shared/services/*` (e.g. `sharedDiscordService`) is exempt.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      ExportNamedDeclaration(node) {
+        if (!node.declaration) return;
+        const decl = node.declaration;
+        if (decl.type !== "FunctionDeclaration") return;
+        if (!decl.async) return;
+        if (!decl.id) return;
+        const funcName = decl.id.name;
+        const calls = collectServiceCalls(decl.body);
+        if (calls.length <= 1) return;
+        for (let i = 1; i < calls.length; i++) {
+          context.report({
+            node: calls[i],
+            messageId: "multipleServiceCalls",
+            data: { funcName, count: String(calls.length) },
+          });
+        }
+      },
+    };
+  },
+};

package/src/common/local-plugins/form-state-shape.mjs

@@ -0,0 +1,213 @@
+/**
+ * Enforce the canonical `{ data, error: { message } }` shape for FormState types.
+ *
+ * Targets `TSInterfaceDeclaration` and `TSTypeAliasDeclaration` whose name ends
+ * with `FormState`. Required shape:
+ *
+ * ```ts
+ * interface XxxFormState {
+ *   data: T | null;            // T may be any type; `data: null` literal also OK
+ *   error: { message: string } | null;
+ * }
+ * ```
+ *
+ * Why this shape:
+ *
+ * - Single uniform shape lets entry / hook / UI be templated and lint-checked.
+ * - Forbids `code` / `status` / similar discriminator fields that tend to grow
+ *   defensive branches (e.g. `error.code === "unauthenticated"`) which usually
+ *   indicate a missing upstream guard (route gate, button conditional render),
+ *   not a legitimate need for in-action discrimination.
+ * - Discriminated unions (`{ data: T; error: null } | { data: null; error: ... }`)
+ *   are rejected for the same reason — they leak shape complexity into hooks
+ *   (`useActionState<T | null>`), components (`state?.error`), and entries.
+ *
+ * Future extension when Stripe / payment libraries actually need `code` / `status`:
+ *
+ * - a) Add a `// allow-error-code: <reason>` comment opt-out to this rule, so
+ *      individual FormStates can justify their extra field on the previous line.
+ * - b) Change the rule to whitelist a fixed set of allowed extra fields (enum
+ *      of standard error codes shared across the codebase).
+ *
+ * Until that need materializes, this rule is strict (no opt-out) per YAGNI.
+ */
+
+const FORM_STATE_SUFFIX = "FormState";
+
+function isNullLiteralType(node) {
+  return node?.type === "TSNullKeyword";
+}
+
+function isStringType(node) {
+  return node?.type === "TSStringKeyword";
+}
+
+function isUnionContainingNull(node) {
+  if (node?.type !== "TSUnionType") return false;
+  return node.types.some(isNullLiteralType);
+}
+
+function getNonNullUnionMembers(unionNode) {
+  return unionNode.types.filter((t) => !isNullLiteralType(t));
+}
+
+function dataTypeAllowsNull(node) {
+  if (!node) return false;
+  if (isNullLiteralType(node)) return true;
+  return isUnionContainingNull(node);
+}
+
+function getErrorObjectExtraFields(node) {
+  if (node?.type !== "TSTypeLiteral") return [];
+  return node.members
+    .filter((m) => m.type === "TSPropertySignature")
+    .filter((m) => m.key?.type === "Identifier" && m.key.name !== "message")
+    .map((m) => m.key.name);
+}
+
+function isErrorMessageOnlyShape(node) {
+  if (node?.type !== "TSTypeLiteral") return false;
+  if (node.members.length !== 1) return false;
+  const member = node.members[0];
+  if (member.type !== "TSPropertySignature") return false;
+  if (member.key?.type !== "Identifier" || member.key.name !== "message") return false;
+  const typeAnn = member.typeAnnotation?.typeAnnotation;
+  return isStringType(typeAnn);
+}
+
+function checkBody(context, idNode, name, members) {
+  const props = new Map();
+  for (const m of members) {
+    if (m.type !== "TSPropertySignature") continue;
+    if (m.key?.type !== "Identifier") continue;
+    props.set(m.key.name, m);
+  }
+
+  const dataProp = props.get("data");
+  if (!dataProp) {
+    context.report({
+      node: idNode,
+      messageId: "dataMissing",
+      data: { name },
+    });
+  } else {
+    const dataType = dataProp.typeAnnotation?.typeAnnotation;
+    if (!dataTypeAllowsNull(dataType)) {
+      context.report({
+        node: dataProp,
+        messageId: "dataNotNullable",
+        data: { name },
+      });
+    }
+  }
+
+  const errorProp = props.get("error");
+  if (!errorProp) {
+    context.report({
+      node: idNode,
+      messageId: "errorMissing",
+      data: { name },
+    });
+  } else {
+    const errorType = errorProp.typeAnnotation?.typeAnnotation;
+    if (!isUnionContainingNull(errorType)) {
+      context.report({
+        node: errorProp,
+        messageId: "errorNotNullable",
+        data: { name },
+      });
+    } else {
+      const nonNull = getNonNullUnionMembers(errorType);
+      if (nonNull.length !== 1) {
+        context.report({
+          node: errorProp,
+          messageId: "errorWrongShape",
+          data: { name },
+        });
+      } else {
+        const errorObj = nonNull[0];
+        if (!isErrorMessageOnlyShape(errorObj)) {
+          const extras = getErrorObjectExtraFields(errorObj);
+          if (extras.length > 0) {
+            for (const extra of extras) {
+              context.report({
+                node: errorProp,
+                messageId: "errorExtraField",
+                data: { name, field: extra },
+              });
+            }
+          } else {
+            context.report({
+              node: errorProp,
+              messageId: "errorWrongShape",
+              data: { name },
+            });
+          }
+        }
+      }
+    }
+  }
+
+  for (const [propName, propNode] of props) {
+    if (propName !== "data" && propName !== "error") {
+      context.report({
+        node: propNode,
+        messageId: "extraProperty",
+        data: { name, field: propName },
+      });
+    }
+  }
+}
+
+export const formStateShapeRule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "Enforce { data, error: { message } } shape for FormState types.",
+    },
+    messages: {
+      dataMissing:
+        "FormState '{{ name }}' must have a `data` property (use `data: null` if there is no payload).",
+      dataNotNullable:
+        "FormState '{{ name }}' `data` must allow null (e.g. `data: T | null` or `data: null`).",
+      errorMissing:
+        "FormState '{{ name }}' must have an `error: { message: string } | null` property.",
+      errorNotNullable:
+        "FormState '{{ name }}' `error` must be nullable (`{ message: string } | null`).",
+      errorWrongShape:
+        "FormState '{{ name }}' `error` must be exactly `{ message: string } | null`.",
+      errorExtraField:
+        "FormState '{{ name }}' `error` object must contain only `message: string`. Forbidden field: '{{ field }}'. See form-state-shape rule docstring for the rationale and the future opt-out plan for Stripe-like cases.",
+      extraProperty:
+        "FormState '{{ name }}' must contain only `data` and `error`. Forbidden property: '{{ field }}'.",
+      discriminatedUnion:
+        "FormState '{{ name }}' must be a single interface or type literal, not a discriminated union.",
+    },
+    schema: [],
+  },
+  create(context) {
+    return {
+      TSInterfaceDeclaration(node) {
+        const name = node.id?.name;
+        if (!name?.endsWith(FORM_STATE_SUFFIX)) return;
+        checkBody(context, node.id, name, node.body.body);
+      },
+      TSTypeAliasDeclaration(node) {
+        const name = node.id?.name;
+        if (!name?.endsWith(FORM_STATE_SUFFIX)) return;
+        const ann = node.typeAnnotation;
+        if (ann?.type === "TSUnionType") {
+          context.report({
+            node: node.id,
+            messageId: "discriminatedUnion",
+            data: { name },
+          });
+          return;
+        }
+        if (ann?.type !== "TSTypeLiteral") return;
+        checkBody(context, node.id, name, ann.members);
+      },
+    };
+  },
+};

package/src/common/local-plugins/index.mjs

@@ -1,6 +1,8 @@
+import { entrySingleServiceCallRule } from "./entry-single-service-call.mjs";
 import { entryTemplateRule } from "./entry-template.mjs";
 import { featureNameRule } from "./feature-name.mjs";
 import { formStateNamingRule } from "./form-state-naming.mjs";
+import { formStateShapeRule } from "./form-state-shape.mjs";
 import { importPathStyleRule } from "./import-path-style.mjs";
 import { layoutMainStructuralOnlyRule } from "./layout-main-structural-only.mjs";
 import { namespaceImportNameRule } from "./namespace-import-name.mjs";
@@ -14,9 +16,11 @@ import { supabaseSelectTypedColumnsRule } from "./supabase-select-typed-columns.
 /** Single plugin object to avoid ESLint "Cannot redefine plugin" errors. */
 export const localPlugin = {
   rules: {
+    "entry-single-service-call": entrySingleServiceCallRule,
     "entry-template": entryTemplateRule,
     "feature-name": featureNameRule,
     "form-state-naming": formStateNamingRule,
+    "form-state-shape": formStateShapeRule,
     "import-path-style": importPathStyleRule,
     "layout-main-structural-only": layoutMainStructuralOnlyRule,
     "namespace-import-name": namespaceImportNameRule,

package/src/common/naming.mjs

@@ -151,6 +151,7 @@ export function createNamingConfigs(featureRoot, prefixLibMapping) {
       plugins: { local: localPlugin },
       rules: {
         "local/form-state-naming": "error",
+        "local/form-state-shape": "error",
       },
     },
   );
@@ -305,6 +306,15 @@ export function createNamingConfigs(featureRoot, prefixLibMapping) {
     },
   });
 
+  configs.push({
+    name: "naming/entry-single-service-call",
+    files: featuresGlob(featureRoot, "**/entries/*.ts"),
+    plugins: { local: localPlugin },
+    rules: {
+      "local/entry-single-service-call": "error",
+    },
+  });
+
   configs.push(
     {
       name: "naming/entries-shared",