eslint-plugin-use-agnostic 0.1.0

package/library/agnostic20/utilities/flows.js

@@ -0,0 +1,212 @@
+import path from "path";
+
+import {
+  EXTENSIONS,
+  useServerJSXMessageId,
+  importBreaksEffectiveImportRulesMessageId,
+  reExportNotSameMessageId,
+} from "../../_commons/constants/bases.js";
+import {
+  USE_SERVER_LOGICS,
+  USE_SERVER_COMPONENTS,
+  USE_SERVER_FUNCTIONS,
+  USE_CLIENT_LOGICS,
+  USE_CLIENT_COMPONENTS,
+  USE_AGNOSTIC_LOGICS,
+  USE_AGNOSTIC_COMPONENTS,
+  // currentFileEffectiveDirective,
+  // importedFileEffectiveDirective,
+  effectiveDirectiveMessage,
+  specificViolationMessage,
+} from "../constants/bases.js";
+
+import { resolveImportPath } from "../../_commons/utilities/helpers.js";
+import {
+  getDirectiveFromCurrentModule,
+  getDirectiveFromImportedModule,
+  getEffectiveDirective,
+  isImportBlocked,
+  makeMessageFromEffectiveDirective,
+  findSpecificViolationMessage,
+} from "./helpers.js";
+
+/* currentFileFlow */
+
+/**
+ * The flow that begins the import rules enforcement rule, retrieving the valid directive of the current file before comparing it to upcoming valid directives of the files it imports.
+ * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksEffectiveImportRulesMessageId | typeof useServerJSXMessageId, []>>} context The ESLint rule's `context` object.
+ * @returns {{skip: true; currentFileEffectiveDirective: undefined;} | {skip: undefined; currentFileEffectiveDirective: USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS;}} Returns either an object with `skip: true` to disregard or one with the non-null `currentFileEffectiveDirective`.
+ */
+export const currentFileFlow = (context) => {
+  // GETTING THE EXTENSION OF THE CURRENT FILE
+  const currentFileExtension = path.extname(context.filename);
+
+  // fails if the file is not JavaScript (TypeScript)
+  const iscurrentFileJS = EXTENSIONS.some(
+    (ext) => currentFileExtension === ext
+  );
+  if (!iscurrentFileJS) {
+    console.error(
+      "ERROR. Linted files for this rule should only be in JavaScript (TypeScript)."
+    );
+    return { skip: true };
+  }
+
+  /* GETTING THE DIRECTIVE (or lack thereof) OF THE CURRENT FILE */
+  const currentFileDirective = getDirectiveFromCurrentModule(context);
+
+  // reports if a file marked "use server" has a JSX extension
+  if (
+    currentFileDirective === "use server" &&
+    currentFileExtension.endsWith("x")
+  ) {
+    context.report({
+      loc: {
+        start: { line: 1, column: 0 },
+        end: { line: 1, column: context.sourceCode.lines[0].length },
+      },
+      messageId: useServerJSXMessageId,
+    });
+    return { skip: true };
+  }
+
+  // GETTING THE EFFECTIVE DIRECTIVE OF THE CURRENT FILE
+  const currentFileEffectiveDirective = getEffectiveDirective(
+    currentFileDirective,
+    currentFileExtension
+  );
+
+  // fails if one of the seven effective directives has not been obtained
+  if (currentFileEffectiveDirective === null) {
+    console.error("ERROR. Effective directive should never be null.");
+    return { skip: true };
+  }
+
+  return {
+    currentFileEffectiveDirective,
+  };
+};
+
+/* importedFileFlow */
+
+/**
+ * The flow that is shared between import and re-export traversals to obtain the import file's effective directive.
+ * @param {string} currentDir Directory of the file containing the import (from `path.dirname(context.filename)`).
+ * @param {string} importPath The import specifier (e.g., `@/components/Button` or `./utils`).
+ * @param {string} cwd Project root (from `context.cwd`). Caveat: only as an assumption currently.
+ * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksEffectiveImportRulesMessageId | typeof useServerJSXMessageId, []>>} context The ESLint rule's `context` object.
+ * @param {import('@typescript-eslint/types').TSESTree.ImportDeclaration} node The ESLint `node` of the rule's current traversal.
+ * @returns {{skip: true; importedFileEffectiveDirective: undefined; resolvedImportPath: undefined;} | {skip: undefined; importedFileEffectiveDirective: USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS; resolvedImportPath: string;}} Returns either an object with `skip: true` to disregard or one with the non-null `importedFileEffectiveDirective`.
+ */
+const importedFileFlow = (context, node) => {
+  // finds the full path of the import
+  const resolvedImportPath = resolveImportPath(
+    path.dirname(context.filename),
+    node.source.value,
+    context.cwd
+  );
+
+  // does not operate on paths it did not resolve
+  if (resolvedImportPath === null) return { skip: true };
+  // does not operate on non-JS files
+  const isImportedFileJS = EXTENSIONS.some((ext) =>
+    resolvedImportPath.endsWith(ext)
+  );
+  if (!isImportedFileJS) return { skip: true };
+
+  /* GETTING THE DIRECTIVE (or lack thereof) OF THE IMPORTED FILE */
+  const importedFileDirective =
+    getDirectiveFromImportedModule(resolvedImportPath);
+  // GETTING THE EXTENSION OF THE IMPORTED FILE
+  const importedFileFileExtension = path.extname(resolvedImportPath);
+  // GETTING THE EFFECTIVE DIRECTIVE OF THE IMPORTED FILE
+  const importedFileEffectiveDirective = getEffectiveDirective(
+    importedFileDirective,
+    importedFileFileExtension
+  );
+
+  // also fails if one of the seven effective directives has not been obtained
+  if (importedFileEffectiveDirective === null) {
+    console.error("ERROR. Effective directive should never be null.");
+    return { skip: true };
+  }
+
+  // For now skipping on both "does not operate" (which should ignore) and "fails" albeit with console.error (which should crash).
+
+  return {
+    importedFileEffectiveDirective,
+  };
+};
+
+/* importsFlow */
+
+/** The full flow for import traversals to enforce effective directives import rules.
+ * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksEffectiveImportRulesMessageId | typeof useServerJSXMessageId, []>>} context The ESLint rule's `context` object.
+ * @param {import('@typescript-eslint/types').TSESTree.ImportDeclaration} node The ESLint `node` of the rule's current traversal.
+ * @param {USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS} currentFileEffectiveDirective The current file's effective directive.
+ * @returns Returns early if the flow needs to be interrupted.
+ */
+export const importsFlow = (context, node, currentFileEffectiveDirective) => {
+  // does not operate on `import type`
+  if (node.importKind === "type") return;
+
+  const result = importedFileFlow(context, node);
+
+  if (result.skip) return;
+  const { importedFileEffectiveDirective } = result;
+
+  if (
+    isImportBlocked(
+      currentFileEffectiveDirective,
+      importedFileEffectiveDirective
+    )
+  ) {
+    context.report({
+      node,
+      messageId: importBreaksEffectiveImportRulesMessageId,
+      data: {
+        [effectiveDirectiveMessage]: makeMessageFromEffectiveDirective(
+          currentFileEffectiveDirective
+        ),
+        [specificViolationMessage]: findSpecificViolationMessage(
+          currentFileEffectiveDirective,
+          importedFileEffectiveDirective
+        ),
+      },
+    });
+  }
+};
+
+/* reExportsFlow */
+
+/** The full flow for export traversals, shared between `ExportNamedDeclaration` and `ExportAllDeclaration`, to ensure same effective directive re-exports.
+ * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksEffectiveImportRulesMessageId | typeof useServerJSXMessageId, []>>} context The ESLint rule's `context` object.
+ * @param {import('@typescript-eslint/types').TSESTree.ExportNamedDeclaration | import('@typescript-eslint/types').TSESTree.ExportAllDeclaration} node The ESLint `node` of the rule's current traversal.
+ * @param {USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS} currentFileEffectiveDirective The current file's effective directive.
+ * @returns Returns early if the flow needs to be interrupted.
+ */
+export const reExportsFlow = (context, node, currentFileEffectiveDirective) => {
+  // does not operate on `export type`
+  if (node.exportKind === "type") return;
+
+  // does not operate on internal exports
+  if (node.source === null) return;
+
+  const result = importedFileFlow(context, node);
+
+  if (result.skip) return;
+  const { importedFileEffectiveDirective } = result;
+
+  if (currentFileEffectiveDirective !== importedFileEffectiveDirective) {
+    context.report({
+      node,
+      messageId: reExportNotSameMessageId,
+      data: {
+        // currentFileEffectiveDirective
+        currentFileEffectiveDirective,
+        // importedFileEffectiveDirective
+        importedFileEffectiveDirective,
+      },
+    });
+  }
+};

package/library/agnostic20/utilities/helpers.js

@@ -0,0 +1,186 @@
+import {
+  useServerJSXMessageId,
+  importBreaksEffectiveImportRulesMessageId,
+  reExportNotSameMessageId,
+  TSX,
+  TS,
+  JSX,
+  JS,
+  MJS,
+  CJS,
+} from "../../_commons/constants/bases.js";
+import {
+  NO_DIRECTIVE,
+  USE_SERVER,
+  USE_CLIENT,
+  USE_AGNOSTIC,
+  USE_SERVER_LOGICS,
+  USE_SERVER_COMPONENTS,
+  USE_SERVER_FUNCTIONS,
+  USE_CLIENT_LOGICS,
+  USE_CLIENT_COMPONENTS,
+  USE_AGNOSTIC_LOGICS,
+  USE_AGNOSTIC_COMPONENTS,
+  effectiveDirectives_EffectiveModules,
+  directivesSet,
+  directivesArray,
+  effectiveDirectives_BlockedImports,
+} from "../constants/bases.js";
+
+import {
+  getImportedFileFirstLine,
+  isImportBlocked as commonsIsImportBlocked,
+  makeMessageFromResolvedDirective,
+  findSpecificViolationMessage as commonsFindSpecificViolationMessage,
+} from "../../_commons/utilities/helpers.js";
+
+/* getDirectiveFromCurrentModule */
+
+/**
+ * Gets the directive of the current module.
+ * - `null` denotes a server-by-default module, ideally a Server Module.
+ * - `'use client'` denotes a Client Module.
+ * - `'use server'` denotes a Server Functions Module.
+ * - `'use agnostic'` denotes an Agnostic Module (formerly Shared Module).
+ * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksEffectiveImportRulesMessageId | typeof useServerJSXMessageId, []>>} context The ESLint rule's `context` object.
+ * @returns {NO_DIRECTIVE | USE_SERVER | USE_CLIENT | USE_AGNOSTIC} The directive, or lack thereof via `null`. The lack of a directive is considered server-by-default.
+ */
+export const getDirectiveFromCurrentModule = (context) => {
+  // the AST body to check for the top-of-the-file directive
+  const { body } = context.sourceCode.ast;
+
+  // the first statement from the source code's Abstract Syntax Tree
+  const firstStatement = body[0];
+
+  // the value of that first statement or null
+  const value =
+    firstStatement?.type === "ExpressionStatement" &&
+    firstStatement.expression?.type === "Literal"
+      ? firstStatement.expression.value
+      : null;
+
+  // considers early a null value as the absence of a directive
+  if (value === null) return value;
+
+  // the value to be exactly 'use client', 'use server' or 'use agnostic' in order not to be considered null by default, or server-by-default
+  const currentFileDirective = directivesSet.has(value) ? value : null;
+
+  return currentFileDirective;
+};
+
+/* getEffectiveDirective */
+
+/**
+ * Gets the effective directive of a module, based on the combination of its directive (or lack thereof) and its extension (depending on whether it ends with 'x' for JSX).
+ * - `'use server logics'` denotes a Server Logics Module.
+ * - `'use server components'` denotes a Server Components Module.
+ * - `'use server functions'` denotes a Server Functions Module.
+ * - `'use client logics'` denotes a Client Logics Module.
+ * - `'use client components'` denotes a Client Components Module.
+ * - `'use agnostic logics'` denotes an Agnostic Logics Module.
+ * - `'use agnostic components'` denotes an Agnostic Components Module.
+ * @param {NO_DIRECTIVE | USE_SERVER | USE_CLIENT | USE_AGNOSTIC} directive The directive as written on top of the file (`null` if no valid directive).
+ * @param {TSX | TS | JSX | JS | MJS | CJS} extension The JavaScript (TypeScript) extension of the file.
+ * @returns {USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS | null} The effective directive, from which imports rules are applied.
+ */
+export const getEffectiveDirective = (directive, extension) => {
+  // I could use a map, but because this is in JS with JSDoc, a manual solution is peculiarly more typesafe.
+  if (directive === NO_DIRECTIVE && !extension.endsWith("x"))
+    return USE_SERVER_LOGICS;
+  if (directive === NO_DIRECTIVE && extension.endsWith("x"))
+    return USE_SERVER_COMPONENTS;
+  if (directive === USE_SERVER && !extension.endsWith("x"))
+    return USE_SERVER_FUNCTIONS;
+  if (directive === USE_CLIENT && !extension.endsWith("x"))
+    return USE_CLIENT_LOGICS;
+  if (directive === USE_CLIENT && extension.endsWith("x"))
+    return USE_CLIENT_COMPONENTS;
+  if (directive === USE_AGNOSTIC && !extension.endsWith("x"))
+    return USE_AGNOSTIC_LOGICS;
+  if (directive === USE_AGNOSTIC && extension.endsWith("x"))
+    return USE_AGNOSTIC_COMPONENTS;
+
+  return null; // default error, should be unreachable
+};
+
+/* getDirectiveFromImportedModule */
+
+/**
+ * Gets the directive of the imported module.
+ * - `'use client'` denotes a Client Module.
+ * - `'use server'` denotes a Server Functions Module.
+ * - `'use agnostic'` denotes an Agnostic Module (formerly Shared Module).
+ * - `null` denotes a server-by-default module, ideally a Server Module.
+ * @param {string} resolvedImportPath The resolved path of the import.
+ * @returns {USE_SERVER | USE_CLIENT | USE_AGNOSTIC | NO_DIRECTIVE} The directive, or lack thereof via `null`. The lack of a directive is considered server-by-default.
+ */
+export const getDirectiveFromImportedModule = (resolvedImportPath) => {
+  // gets the first line of the code of the import
+  const importedFileFirstLine = getImportedFileFirstLine(resolvedImportPath);
+
+  // verifies that this first line starts with a valid directive, thus excluding comments
+  const hasAcceptedDirective = directivesArray.some(
+    (directive) =>
+      importedFileFirstLine.startsWith(`'${directive}'`) ||
+      importedFileFirstLine.startsWith(`"${directive}"`)
+  );
+
+  // applies the correct directive or the lack thereof with null
+  const importedFileDirective = hasAcceptedDirective
+    ? directivesArray.find((directive) =>
+        importedFileFirstLine.includes(directive)
+      ) ?? null
+    : null;
+
+  return importedFileDirective;
+};
+
+/* isImportBlocked */
+
+/**
+ * Returns a boolean deciding if an imported file's effective directive is incompatible with the current file's effective directive.
+ * @param {USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS} currentFileEffectiveDirective The current file's effective directive.
+ * @param {USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS} importedFileEffectiveDirective The imported file's effective directive.
+ * @returns {boolean} Returns `true` if the import is blocked, as established in `effectiveDirectives_BlockedImports`.
+ */
+export const isImportBlocked = (
+  currentFileEffectiveDirective,
+  importedFileEffectiveDirective
+) =>
+  commonsIsImportBlocked(
+    effectiveDirectives_BlockedImports,
+    currentFileEffectiveDirective,
+    importedFileEffectiveDirective
+  );
+
+/* makeMessageFromEffectiveDirective */
+
+/**
+ * Lists in an message the effective modules incompatible with an effective module based on its effective directive.
+ * @param {USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS} effectiveDirective The effective directive of the effective module.
+ * @returns {string} The message listing the incompatible effective modules.
+ */
+export const makeMessageFromEffectiveDirective = (effectiveDirective) =>
+  makeMessageFromResolvedDirective(
+    effectiveDirectives_EffectiveModules,
+    effectiveDirectives_BlockedImports,
+    effectiveDirective
+  );
+
+/* findSpecificViolationMessage */
+
+/**
+ * Finds the `message` for the specific violation of effective directives import rules based on `effectiveDirectives_BlockedImports`.
+ * @param {USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS} currentFileEffectiveDirective The current file's effective directive.
+ * @param {USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS} importedFileEffectiveDirective The imported file's effective directive.
+ * @returns {string} The corresponding `message`.
+ */
+export const findSpecificViolationMessage = (
+  currentFileEffectiveDirective,
+  importedFileEffectiveDirective
+) =>
+  commonsFindSpecificViolationMessage(
+    effectiveDirectives_BlockedImports,
+    currentFileEffectiveDirective,
+    importedFileEffectiveDirective
+  );

package/library/directive21/config.js

@@ -0,0 +1,24 @@
+import { defineConfig } from "eslint/config";
+
+import {
+  directive21ConfigName,
+  useAgnosticPluginName,
+  enforceCommentedDirectivesRuleName,
+} from "../_commons/constants/bases.js";
+
+/**
+ * Makes the directive21 config for the use-agnostic ESLint plugin.
+ */
+export const makeDirective21Config = (plugin) => ({
+  [directive21ConfigName]: defineConfig([
+    {
+      plugins: {
+        [useAgnosticPluginName]: plugin,
+      },
+      rules: {
+        [`${useAgnosticPluginName}/${enforceCommentedDirectivesRuleName}`]:
+          "warn",
+      },
+    },
+  ]),
+});