part: set up overridable options

Author: RebeccaStevens

package.json

@@ -73,8 +73,9 @@
     "@typescript-eslint/utils": "^7.6.0",
     "deepmerge-ts": "^5.1.0",
     "escape-string-regexp": "^4.0.0",
-    "is-immutable-type": "^3.1.0",
-    "ts-api-utils": "^1.3.0"
+    "is-immutable-type": "^4.0.0",
+    "ts-api-utils": "^1.3.0",
+    "ts-declaration-location": "^1.0.0"
   },
   "devDependencies": {
     "@babel/eslint-parser": "7.24.1",

pnpm-lock.yaml

@@ -1 +1,2 @@
 export * from "./ignore";
+export * from "./overrides";

src/options/index.ts

@@ -0,0 +1,81 @@
+import { type TSESTree } from "@typescript-eslint/utils";
+import { type RuleContext } from "@typescript-eslint/utils/ts-eslint";
+import { deepmerge } from "deepmerge-ts";
+import typeMatchesSpecifier from "ts-declaration-location";
+
+import { getTypeDataOfNode } from "#eslint-plugin-functional/utils/rule";
+import {
+  type TypeSpecifier,
+  typeMatchesPattern,
+} from "#eslint-plugin-functional/utils/type-specifier";
+
+/**
+ * Options that can be overridden.
+ */
+export type OverridableOptions<CoreOptions> = CoreOptions & {
+  overrides?: Array<
+    {
+      specifiers: TypeSpecifier | TypeSpecifier[];
+    } & (
+      | {
+          options: CoreOptions;
+          inherit?: boolean;
+          disable?: false;
+        }
+      | {
+          disable: true;
+        }
+    )
+  >;
+};
+
+/**
+ * Get the core options to use, taking into account overrides.
+ */
+export function getCoreOptions<
+  CoreOptions extends object,
+  Options extends readonly [Readonly<OverridableOptions<CoreOptions>>],
+>(
+  node: TSESTree.Node,
+  context: Readonly<RuleContext<string, Options>>,
+  options: Readonly<Options>,
+): CoreOptions | null {
+  const [optionsObject] = options;
+
+  const program = context.sourceCode.parserServices?.program ?? undefined;
+  if (program === undefined) {
+    return optionsObject;
+  }
+
+  const [type, typeNode] = getTypeDataOfNode(node, context);
+  const found = optionsObject.overrides?.find((override) =>
+    (Array.isArray(override.specifiers)
+      ? override.specifiers
+      : [override.specifiers]
+    ).some(
+      (specifier) =>
+        typeMatchesSpecifier(program, specifier, type) &&
+        (specifier.include === undefined ||
+          specifier.include.length === 0 ||
+          typeMatchesPattern(
+            program,
+            type,
+            typeNode,
+            specifier.include,
+            specifier.exclude,
+          )),
+    ),
+  );
+
+  if (found !== undefined) {
+    if (found.disable === true) {
+      return null;
+    }
+    if (found.inherit !== false) {
+      return deepmerge(optionsObject, found.options) as CoreOptions;
+    }
+    return found.options;
+  }
+
+  return optionsObject;
+}

src/options/overrides.ts

@@ -1,3 +1,5 @@
+import assert from "node:assert/strict";
+
 import { type TSESTree } from "@typescript-eslint/utils";
 import {
   type NamedCreateRuleMeta,
@@ -21,6 +23,8 @@ import { getImmutabilityOverrides } from "#eslint-plugin-functional/settings";
 import { __VERSION__ } from "#eslint-plugin-functional/utils/constants";
 import { type ESFunction } from "#eslint-plugin-functional/utils/node-types";
 
+import { typeMatchesPattern } from "./type-specifier";
+
 /**
  * Any custom rule meta properties.
  */
@@ -187,10 +191,49 @@ export function getTypeOfNode<Context extends RuleContext<string, BaseOptions>>(
   node: TSESTree.Node,
   context: Context,
 ): Type {
+  assert(ts !== undefined);
+
   const { esTreeNodeToTSNodeMap } = getParserServices(context);
 
   const tsNode = esTreeNodeToTSNodeMap.get(node);
-  return getTypeOfTSNode(tsNode, context);
+  const typedNode = ts.isIdentifier(tsNode) ? tsNode.parent : tsNode;
+  return getTypeOfTSNode(typedNode, context);
+}
+
+/**
+ * Get the type of the the given node.
+ */
+export function getTypeNodeOfNode<
+  Context extends RuleContext<string, BaseOptions>,
+>(node: TSESTree.Node, context: Context): TypeNode | null {
+  assert(ts !== undefined);
+
+  const { esTreeNodeToTSNodeMap } = getParserServices(context);
+
+  const tsNode = esTreeNodeToTSNodeMap.get(node);
+  const typedNode = (
+    ts.isIdentifier(tsNode) ? tsNode.parent : tsNode
+  ) as TSNode & { type?: TypeNode };
+  return typedNode.type ?? null;
+}
+
+/**
+ * Get the type of the the given node.
+ */
+export function getTypeDataOfNode<
+  Context extends RuleContext<string, BaseOptions>,
+>(node: TSESTree.Node, context: Context): [Type, TypeNode | null] {
+  assert(ts !== undefined);
+
+  const { esTreeNodeToTSNodeMap } = getParserServices(context);
+
+  const tsNode = esTreeNodeToTSNodeMap.get(node);
+  const typedNode = (
+    ts.isIdentifier(tsNode) ? tsNode.parent : tsNode
+  ) as TSNode & {
+    type?: TypeNode;
+  };
+  return [getTypeOfTSNode(typedNode, context), typedNode.type ?? null];
 }
 
 /**
@@ -275,6 +318,7 @@ export function getTypeImmutabilityOfNode<
     // Don't use the global cache in testing environments as it may cause errors when switching between different config options.
     process.env["NODE_ENV"] !== "test",
     maxImmutability,
+    typeMatchesPattern,
   );
 }
 

src/utils/rule.ts

@@ -0,0 +1,81 @@
+import {
+  type JSONSchema4,
+  type JSONSchema4ObjectSchema,
+} from "@typescript-eslint/utils/json-schema";
+
+const typeSpecifierPatternSchemaProperties: JSONSchema4ObjectSchema["properties"] =
+  {
+    name: schemaInstanceOrInstanceArray({
+      type: "string",
+    }),
+    pattern: schemaInstanceOrInstanceArray({
+      type: "string",
+    }),
+    ignoreName: schemaInstanceOrInstanceArray({
+      type: "string",
+    }),
+    ignorePattern: schemaInstanceOrInstanceArray({
+      type: "string",
+    }),
+  };
+
+const typeSpecifierSchema: JSONSchema4 = {
+  oneOf: [
+    {
+      type: "object",
+      properties: {
+        ...typeSpecifierPatternSchemaProperties,
+        from: {
+          type: "string",
+          enum: ["file"],
+        },
+        path: {
+          type: "string",
+        },
+      },
+      additionalProperties: false,
+    },
+    {
+      type: "object",
+      properties: {
+        ...typeSpecifierPatternSchemaProperties,
+        from: {
+          type: "string",
+          enum: ["lib"],
+        },
+      },
+      additionalProperties: false,
+    },
+    {
+      type: "object",
+      properties: {
+        ...typeSpecifierPatternSchemaProperties,
+        from: {
+          type: "string",
+          enum: ["package"],
+        },
+        package: {
+          type: "string",
+        },
+      },
+      additionalProperties: false,
+    },
+  ],
+};
+
+export const typeSpecifiersSchema: JSONSchema4 =
+  schemaInstanceOrInstanceArray(typeSpecifierSchema);
+
+export function schemaInstanceOrInstanceArray(
+  items: JSONSchema4,
+): NonNullable<JSONSchema4ObjectSchema["properties"]>[string] {
+  return {
+    oneOf: [
+      items,
+      {
+        type: "array",
+        items,
+      },
+    ],
+  };
+}