eslint-plugin-use-agnostic 0.1.0

package/library/directive21/utilities/flows.js

@@ -0,0 +1,268 @@
+import path from "path";
+
+import {
+  EXTENSIONS,
+  reExportNotSameMessageId,
+  importBreaksCommentedImportRulesMessageId,
+  noCommentedDirective,
+  commentedDirectiveVerificationFailed,
+  importNotStrategized,
+  exportNotStrategized,
+} from "../../_commons/constants/bases.js";
+import {
+  USE_SERVER_LOGICS,
+  USE_CLIENT_LOGICS,
+  USE_AGNOSTIC_LOGICS,
+  USE_SERVER_COMPONENTS,
+  USE_CLIENT_COMPONENTS,
+  USE_AGNOSTIC_COMPONENTS,
+  USE_SERVER_FUNCTIONS,
+  USE_CLIENT_CONTEXTS,
+  USE_AGNOSTIC_CONDITIONS,
+  USE_AGNOSTIC_STRATEGIES,
+  commentedDirectives_VerificationReports,
+  // currentFileCommentedDirective,
+  // importedFileCommentedDirective,
+  commentedDirectiveMessage,
+  specificViolationMessage,
+  specificFailure,
+} from "../constants/bases.js";
+
+import { resolveImportPath } from "../../_commons/utilities/helpers.js";
+import {
+  getCommentedDirectiveFromCurrentModule,
+  getVerifiedCommentedDirective,
+  getCommentedDirectiveFromImportedModule,
+  isImportBlocked,
+  makeMessageFromCommentedDirective,
+  findSpecificViolationMessage,
+  getStrategizedDirective,
+} 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 importBreaksCommentedImportRulesMessageId | typeof noCommentedDirective | typeof commentedDirectiveVerificationFailed | typeof importNotStrategized | typeof exportNotStrategized, []>>} context The ESLint rule's `context` object.
+ * @returns {{skip: true; verifiedCommentedDirective: undefined;} | {skip: undefined; verifiedCommentedDirective: USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES;}} Returns either an object with `skip: true` to disregard or one with the non-null `verifiedCommentedDirective`.
+ */
+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 };
+  }
+
+  // gets the commented directive from the current file
+  const commentedDirective = getCommentedDirectiveFromCurrentModule(context);
+
+  // reports if there is no directive or no valid directive (same, but eventually no directive could have defaults)
+  if (!commentedDirective) {
+    context.report({
+      loc: {
+        start: { line: 1, column: 0 },
+        end: { line: 1, column: context.sourceCode.lines[0].length },
+      },
+      messageId: noCommentedDirective,
+    });
+    return { skip: true };
+  }
+
+  const verifiedCommentedDirective = getVerifiedCommentedDirective(
+    commentedDirective,
+    currentFileExtension
+  );
+
+  // reports if the verification failed
+  if (!verifiedCommentedDirective) {
+    context.report({
+      loc: {
+        start: { line: 1, column: 0 },
+        end: { line: 1, column: context.sourceCode.lines[0].length },
+      },
+      messageId: commentedDirectiveVerificationFailed,
+      data: {
+        [specificFailure]:
+          commentedDirectives_VerificationReports[commentedDirective],
+      },
+    });
+    return { skip: true };
+  }
+
+  return {
+    verifiedCommentedDirective,
+  };
+};
+
+/* importedFileFlow */
+
+/**
+ * The flow that is shared between import and re-export traversals to obtain the import file's commented directive.
+ * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksCommentedImportRulesMessageId | typeof noCommentedDirective | typeof commentedDirectiveVerificationFailed | typeof importNotStrategized | typeof exportNotStrategized, []>>} 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; importedFileCommentedDirective: undefined;} | {skip: undefined; importedFileCommentedDirective: USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS;}} Returns either an object with `skip: true` to disregard or one with the non-null `importedFileCommentedDirective`.
+ */
+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 */
+  let importedFileCommentedDirective =
+    getCommentedDirectiveFromImportedModule(resolvedImportPath);
+
+  // returns early if there is no directive or no valid directive (same, but eventually no directive could have defaults)
+  if (!importedFileCommentedDirective) {
+    console.warn(
+      "The imported file, whose path has been resolved, has no directive. It is thus ignored since the report on that circumstance is available on the imported file itself."
+    );
+    return { skip: true };
+  }
+
+  /* GETTING THE CORRECT DIRECTIVE INTERPRETATION OF STRATEGY FOR AGNOSTIC STRATEGIES MODULES IMPORTS. 
+  (The Directive-First Architecture does not check whether the export and import Strategies are the same at this time, meaning a @clientLogics strategy could be wrongly imported and interpreted as a @serverLogics strategy. However, Strategy exports are plan to be linting in the future within their own Agnostic Strategies Modules to ensure they respect import rules within their own scopes. It may also become possible to check whether the export and import Strategies are the same in the future when identifiers are defined and the same, especially for components modules where a convention could be to for all non-type export to be named and PascalCase.) */
+  if (importedFileCommentedDirective === USE_AGNOSTIC_STRATEGIES) {
+    importedFileCommentedDirective = getStrategizedDirective(context, node);
+
+    if (importedFileCommentedDirective === null) {
+      context.report({
+        node,
+        messageId: importNotStrategized,
+      });
+      return { skip: true };
+    }
+  }
+
+  return { importedFileCommentedDirective };
+};
+
+/* importsFlow */
+
+/**
+ * The full flow for import traversals to enforce effective directives import rules.
+ * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksCommentedImportRulesMessageId | typeof noCommentedDirective | typeof commentedDirectiveVerificationFailed | typeof importNotStrategized | typeof exportNotStrategized, []>>} 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_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES} currentFileCommentedDirective The current file's commented directive.
+ * @returns Returns early if the flow needs to be interrupted.
+ */
+export const importsFlow = (context, node, currentFileCommentedDirective) => {
+  // does not operate on `import type`
+  if (node.importKind === "type") return;
+
+  const result = importedFileFlow(context, node);
+
+  if (result.skip) return;
+  const { importedFileCommentedDirective } = result;
+
+  if (
+    isImportBlocked(
+      currentFileCommentedDirective,
+      importedFileCommentedDirective
+    )
+  ) {
+    context.report({
+      node,
+      messageId: importBreaksCommentedImportRulesMessageId,
+      data: {
+        [commentedDirectiveMessage]: makeMessageFromCommentedDirective(
+          currentFileCommentedDirective
+        ),
+        [specificViolationMessage]: findSpecificViolationMessage(
+          currentFileCommentedDirective,
+          importedFileCommentedDirective
+        ),
+      },
+    });
+  }
+};
+
+/* allExportsFlow */
+
+/**
+ * The full flow for export traversals, shared between `ExportNamedDeclaration`, `ExportAllDeclaration`, and `ExportDefaultDeclaration`, to ensure same commented directive re-exports in modules that aren't Agnostic Strategies Modules, and enforce strategized exports specifically in Agnostic Strategies Modules.
+ * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksCommentedImportRulesMessageId | typeof noCommentedDirective | typeof commentedDirectiveVerificationFailed | typeof importNotStrategized | typeof exportNotStrategized, []>>} context The ESLint rule's `context` object.
+ * @param {import('@typescript-eslint/types').TSESTree.ExportNamedDeclaration | import('@typescript-eslint/types').TSESTree.ExportAllDeclaration | import('@typescript-eslint/types').TSESTree.ExportDefaultDeclaration} node The ESLint `node` of the rule's current traversal.
+ * @param {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES} currentFileCommentedDirective The current file's commented directive.
+ * @returns Returns early if the flow needs to be interrupted.
+ */
+export const allExportsFlow = (
+  context,
+  node,
+  currentFileCommentedDirective
+) => {
+  // does not operate on `export type`
+  if (node.exportKind === "type") return;
+
+  if (node.source) {
+    const result = importedFileFlow(context, node);
+
+    if (result.skip) return;
+    const { importedFileCommentedDirective } = result;
+
+    // ignores if this is NOT an Agnostic Strategies Module
+    // verifies current node export strategy if "use agnostic strategies"
+    if (currentFileCommentedDirective === USE_AGNOSTIC_STRATEGIES) {
+      const exportStrategizedDirective = getStrategizedDirective(context, node);
+
+      if (exportStrategizedDirective === null) {
+        context.report({
+          node,
+          messageId: exportNotStrategized,
+        });
+        return;
+      }
+
+      currentFileCommentedDirective = exportStrategizedDirective;
+    }
+
+    if (currentFileCommentedDirective !== importedFileCommentedDirective) {
+      context.report({
+        node,
+        messageId: reExportNotSameMessageId,
+        data: {
+          // currentFileCommentedDirective
+          currentFileCommentedDirective,
+          // importedFileCommentedDirective
+          importedFileCommentedDirective,
+        },
+      });
+      return;
+    }
+  } else {
+    // ignores if this is NOT an Agnostic Strategies Module
+    // verifies current node export strategy if "use agnostic strategies"
+    if (currentFileCommentedDirective === USE_AGNOSTIC_STRATEGIES) {
+      const exportStrategizedDirective = getStrategizedDirective(context, node);
+
+      if (exportStrategizedDirective === null) {
+        context.report({
+          node,
+          messageId: exportNotStrategized,
+        });
+        return;
+      }
+
+      // just to emphasize that this is the same short flow from above
+      currentFileCommentedDirective = exportStrategizedDirective;
+    }
+  }
+};

package/library/directive21/utilities/helpers.js

@@ -0,0 +1,291 @@
+import {
+  reExportNotSameMessageId,
+  importBreaksCommentedImportRulesMessageId,
+  noCommentedDirective,
+  commentedDirectiveVerificationFailed,
+  importNotStrategized,
+  exportNotStrategized,
+} from "../../_commons/constants/bases.js";
+import {
+  USE_SERVER_LOGICS,
+  USE_CLIENT_LOGICS,
+  USE_AGNOSTIC_LOGICS,
+  USE_SERVER_COMPONENTS,
+  USE_CLIENT_COMPONENTS,
+  USE_AGNOSTIC_COMPONENTS,
+  USE_SERVER_FUNCTIONS,
+  USE_CLIENT_CONTEXTS,
+  USE_AGNOSTIC_CONDITIONS,
+  USE_AGNOSTIC_STRATEGIES,
+  directivesSet,
+  directivesArray,
+  commentedDirectives_4RawImplementations,
+  commentedStrategies_CommentedDirectives,
+  commentedDirectives_BlockedImports,
+  commentedDirectives_CommentedModules,
+} from "../constants/bases.js";
+
+import {
+  getImportedFileFirstLine,
+  isImportBlocked as commonsIsImportBlocked,
+  makeMessageFromResolvedDirective,
+  findSpecificViolationMessage as commonsFindSpecificViolationMessage,
+} from "../../_commons/utilities/helpers.js";
+
+/* getCommentedDirectiveFromCurrentModule */
+
+/**
+ * Gets the commented directive of the current module.
+ *
+ * Accepted directives for the default Directive-First Architecture are (single or double quotes included):
+ * - `'use server logics'`, `"use server logics"` denoting a Server Logics Module.
+ * - `'use client logics'`, `"use client logics"` denoting a Client Logics Module.
+ * - `'use agnostic logics'`, `"use agnostic logics"` denoting an Agnostic Logics Module.
+ * - `'use server components'`, `"use server components"` denoting a Server Components Module.
+ * - `'use client components'`, `"use client components"` denoting a Client Components Module.
+ * - `'use agnostic components'`, `"use agnostic components"` denoting an Agnostic Components Module.
+ * - `'use agnostic logics'`, `"use agnostic logics"` denoting an Agnostic Logics Module.
+ * - `'use server functions'`, `"use server functions"` denoting a Server Functions Module.
+ * - `'use client contexts'`, `"use client contexts"` denoting a Client Contexts Module.
+ * - `'use agnostic conditions'`, `"use agnostic conditions"` denoting an Agnostic Conditions Module.
+ * - `'use agnostic strategies'`, `"use agnostic strategies"` denoting an Agnostic Strategies Module.
+ * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksCommentedImportRulesMessageId | typeof noCommentedDirective | typeof commentedDirectiveVerificationFailed | typeof importNotStrategized | typeof exportNotStrategized, []>>} context The ESLint rule's `context` object.
+ * @returns {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES | null} The commented directive, or lack thereof via `null`. Given the strictness of this architecture, the lack of a directive is considered a mistake. (Though rules may provide the opportunity to declare a default, and configs with preset defaults may be provided.)
+ */
+export const getCommentedDirectiveFromCurrentModule = (context) => {
+  // gets the first comment from the source code
+  const firstComment = context.sourceCode.getAllComments()[0];
+
+  // returns null early if there is no first comment
+  if (!firstComment) return null;
+
+  // returns null early if the first comment is not on the first line and the first column
+  if (firstComment.loc.start.line !== 1 || firstComment.loc.start.column !== 0)
+    return null;
+
+  // gets the trimmed raw value of the first comment
+  const rawValue = firstComment.value.trim();
+
+  // checks if the raw value is single- or double-quoted (or neither)
+  const isSingleQuoted = detectQuoteType(rawValue);
+
+  // returns null early if the raw value (trimmed prior) is neither single- nor double-quoted
+  if (isSingleQuoted === null) return null;
+
+  // Obtains the value depending on whether the raw value is single- or double-quoted. (Note: The same string is returned if, for some impossible reason, the raw value does not correspond in terms of quote types. It does not matter because the check coming next will always fail to null if that's the case.)
+  const value = isSingleQuoted
+    ? stripSingleQuotes(rawValue)
+    : stripDoubleQuotes(rawValue);
+
+  // certifies the directive or lack thereof from the obtained value
+  const commentedDirective = directivesSet.has(value) ? value : null;
+
+  return commentedDirective;
+};
+
+/**
+ * Detects whether a string is single- or double-quoted.
+ * @param {string} string
+ * @returns
+ */
+const detectQuoteType = (string) => {
+  if (string.startsWith("'") && string.endsWith("'")) {
+    return true; // single quotes
+  } else if (string.startsWith('"') && string.endsWith('"')) {
+    return false; // double quotes
+  } else {
+    return null; // neither
+  }
+};
+
+/**
+ * Removes single quotes from a string known to be single-quoted.
+ * @param {string} string
+ * @returns
+ */
+const stripSingleQuotes = (string) => {
+  if (string.startsWith("'") && string.endsWith("'")) {
+    return string.slice(1, -1);
+  }
+  return string;
+};
+
+/**
+ * Removes double quotes from a string known to be double-quoted.
+ * @param {string} string
+ * @returns
+ */
+const stripDoubleQuotes = (string) => {
+  if (string.startsWith('"') && string.endsWith('"')) {
+    return string.slice(1, -1);
+  }
+  return string;
+};
+
+/* getVerifiedCommentedDirective */
+
+/**
+ * Ensures that a module's commented directive is consistent with its file extension (depending on whether it ends with 'x' for JSX).
+ * - `'use server logics'`: Server Logics Modules do NOT export JSX.
+ * - `'use client logics'`: Client Logics Modules do NOT export JSX.
+ * - `'use agnostic logics'`: Agnostic Logics Modules do NOT export JSX.
+ * - `'use server components'`: Server Components Modules ONLY export JSX.
+ * - `'use client components'`: Client Components Modules ONLY export JSX.
+ * - `'use agnostic components'`: Agnostic Components Modules ONLY export JSX.
+ * - `'use server functions'`: Server Functions Modules do NOT export JSX.
+ * - `'use client contexts'`: Client Contexts Modules ONLY export JSX.
+ * - `'use agnostic conditions'`: Agnostic Conditions Modules ONLY export JSX.
+ * - `'use agnostic strategies'`: Agnostic Strategies Modules may export JSX.
+ * @param {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES} directive The commented directive as written on top of the file (cannot be `null` at that stage).
+ * @param {TSX | TS | JSX | JS | MJS | CJS} extension The JavaScript (TypeScript) extension of the file.
+ * @returns {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES | null} The verified commented directive, from which imports rules are applied. Returns `null` if the verification failed, upon which an error will be reported depending on the commented directive, since the error logic here is strictly binary.
+ */
+export const getVerifiedCommentedDirective = (directive, extension) => {
+  // I could use a map, but because this is in JS with JSDoc, a manual solution is peculiarly more typesafe.
+  if (directive === USE_SERVER_LOGICS && !extension.endsWith("x"))
+    return directive;
+  if (directive === USE_CLIENT_LOGICS && !extension.endsWith("x"))
+    return directive;
+  if (directive === USE_AGNOSTIC_LOGICS && !extension.endsWith("x"))
+    return directive;
+  if (directive === USE_SERVER_COMPONENTS && extension.endsWith("x"))
+    return directive;
+  if (directive === USE_CLIENT_COMPONENTS && extension.endsWith("x"))
+    return directive;
+  if (directive === USE_AGNOSTIC_COMPONENTS && extension.endsWith("x"))
+    return directive;
+  if (directive === USE_SERVER_FUNCTIONS && !extension.endsWith("x"))
+    return directive;
+  if (directive === USE_CLIENT_CONTEXTS && extension.endsWith("x"))
+    return directive;
+  if (directive === USE_AGNOSTIC_CONDITIONS && extension.endsWith("x"))
+    return directive;
+  if (directive === USE_AGNOSTIC_STRATEGIES) return directive;
+
+  return null; // verification error
+};
+
+/* getCommentedDirectiveFromImportedModule */
+
+/**
+ * Gets the commented directive of the imported module.
+ *
+ * Accepted directives for the default Directive-First Architecture are (single or double quotes included):
+ * - `'use server logics'`, `"use server logics"` denoting a Server Logics Module.
+ * - `'use client logics'`, `"use client logics"` denoting a Client Logics Module.
+ * - `'use agnostic logics'`, `"use agnostic logics"` denoting an Agnostic Logics Module.
+ * - `'use server components'`, `"use server components"` denoting a Server Components Module.
+ * - `'use client components'`, `"use client components"` denoting a Client Components Module.
+ * - `'use agnostic components'`, `"use agnostic components"` denoting an Agnostic Components Module.
+ * - `'use agnostic logics'`, `"use agnostic logics"` denoting an Agnostic Logics Module.
+ * - `'use server functions'`, `"use server functions"` denoting a Server Functions Module.
+ * - `'use client contexts'`, `"use client contexts"` denoting a Client Contexts Module.
+ * - `'use agnostic conditions'`, `"use agnostic conditions"` denoting an Agnostic Conditions Module.
+ * - `'use agnostic strategies'`, `"use agnostic strategies"` denoting an Agnostic Strategies Module.
+ * @param {string} resolvedImportPath The resolved path of the import.
+ * @returns {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES | null} The commented directive, or lack thereof via `null`. Given the strictness of this architecture, the lack of a directive is considered a mistake. (Though rules may provide the opportunity to declare a default, and configs with preset defaults may be provided.)
+ */
+export const getCommentedDirectiveFromImportedModule = (resolvedImportPath) => {
+  // gets the first line of the code of the import
+  const importedFileFirstLine = getImportedFileFirstLine(resolvedImportPath);
+
+  // sees if the first line includes any of the directives and finds the directive that it includes
+  let includedDirective = "";
+  const lengthOne = directivesArray.length;
+  for (let i = 0; i < lengthOne; i++) {
+    const directive = directivesArray[i];
+    if (importedFileFirstLine.includes(directive)) {
+      includedDirective = directive;
+      break;
+    }
+  }
+
+  // returns null early if there is none of the directives in the first line
+  if (includedDirective === "") return null;
+
+  let importFileDirective = "";
+  const lengthTwo =
+    // sucks for that any but, I'm working in JS here
+    commentedDirectives_4RawImplementations[includedDirective].length;
+  for (let i = 0; i < lengthTwo; i++) {
+    const raw = commentedDirectives_4RawImplementations[includedDirective][i];
+    if (raw === importedFileFirstLine) {
+      importFileDirective = includedDirective;
+      break;
+    }
+  }
+
+  // returns null early if despite the presence of the directive it is not properly implemented
+  if (importFileDirective === "") return null;
+
+  return importFileDirective;
+};
+
+/* getStrategizedDirective */
+
+/**
+ * Gets the interpreted directive from a specified commented Strategy (such as `@serverLogics`) nested inside the import declaration for an import from an Agnostic Strategies Module.
+ * @param {Readonly<import('@typescript-eslint/utils').TSESLint.RuleContext<typeof reExportNotSameMessageId | typeof importBreaksCommentedImportRulesMessageId | typeof noCommentedDirective | typeof commentedDirectiveVerificationFailed | typeof importNotStrategized | typeof exportNotStrategized, []>>} 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 {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | null} Returns the interpreted directive, a.k.a. strategized directive, or lack thereof via `null`.
+ */
+export const getStrategizedDirective = (context, node) => {
+  const firstNestedComment = context.sourceCode.getCommentsInside(node)[0];
+
+  // returns null early if there is no nested comments
+  if (!firstNestedComment) return null;
+
+  const strategy = firstNestedComment.value.trim() || null;
+
+  return commentedStrategies_CommentedDirectives[strategy] || null;
+};
+
+/* isImportBlocked */
+
+/**
+ * Returns a boolean deciding if an imported file's commented directive is incompatible with the current file's commented directive.
+ * @param {USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS} currentFileCommentedDirective The current file's commented directive.
+ * @param {USE_SERVER_LOGICS | USE_SERVER_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_LOGICS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_LOGICS | USE_AGNOSTIC_COMPONENTS} importedFileCommentedDirective The imported file's commented directive.
+ * @returns {boolean} Returns `true` if the import is blocked, as established in `commentedDirectives_BlockedImports`.
+ */
+export const isImportBlocked = (
+  currentFileCommentedDirective,
+  importedFileCommentedDirective
+) =>
+  commonsIsImportBlocked(
+    commentedDirectives_BlockedImports,
+    currentFileCommentedDirective,
+    importedFileCommentedDirective
+  );
+
+/* makeMessageFromCommentedDirective */
+
+/**
+ * Lists in an message the commented modules incompatible with a commented module based on its commented directive.
+ * @param {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES} commentedDirective The commented directive of the commented module.
+ * @returns {string} The message listing the incompatible commented modules.
+ */
+export const makeMessageFromCommentedDirective = (commentedDirective) =>
+  makeMessageFromResolvedDirective(
+    commentedDirectives_CommentedModules,
+    commentedDirectives_BlockedImports,
+    commentedDirective
+  );
+
+/* findSpecificViolationMessage */
+
+/**
+ * Finds the `message` for the specific violation of commented directives import rules based on `commentedDirectives_BlockedImports`.
+ * @param {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS | USE_AGNOSTIC_STRATEGIES} currentFileCommentedDirective The current file's commented directive.
+ * @param {USE_SERVER_LOGICS | USE_CLIENT_LOGICS | USE_AGNOSTIC_LOGICS | USE_SERVER_COMPONENTS | USE_CLIENT_COMPONENTS | USE_AGNOSTIC_COMPONENTS | USE_SERVER_FUNCTIONS | USE_CLIENT_CONTEXTS | USE_AGNOSTIC_CONDITIONS} importedFileCommentedDirective The imported file's commented directive.
+ * @returns {string} The corresponding `message`.
+ */
+export const findSpecificViolationMessage = (
+  currentFileCommentedDirective,
+  importedFileCommentedDirective
+) =>
+  commonsFindSpecificViolationMessage(
+    commentedDirectives_BlockedImports,
+    currentFileCommentedDirective,
+    importedFileCommentedDirective
+  );

package/library/index.js

@@ -0,0 +1,42 @@
+import fs from "fs";
+
+import {
+  enforceEffectiveDirectivesRuleName,
+  enforceCommentedDirectivesRuleName,
+} from "./_commons/constants/bases.js";
+
+import enforceEffectiveDirectivesImportRules from "./agnostic20/rules/import-rules-enforcement.js";
+import enforceCommentedDirectivesImportRules from "./directive21/rules/import-rules-enforcement.js";
+
+import { makeAgnostic20Config } from "./agnostic20/config.js";
+import { makeDirective21Config } from "./directive21/config.js";
+
+/** @type {import("tsconfig-paths/lib/filesystem.js").PackageJson} */
+const packageDotJSON = JSON.parse(
+  fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")
+);
+
+/** @type {import('eslint').ESLint.Plugin} */
+const plugin = {
+  meta: { ...packageDotJSON },
+  configs: {}, // applied below
+  rules: {
+    [enforceEffectiveDirectivesRuleName]: enforceEffectiveDirectivesImportRules,
+    [enforceCommentedDirectivesRuleName]: enforceCommentedDirectivesImportRules,
+  },
+  processors: {}, // not used
+};
+
+Object.assign(plugin.configs, makeAgnostic20Config(plugin));
+Object.assign(plugin.configs, makeDirective21Config(plugin));
+
+export default plugin;
+
+export {
+  // for use in eslint.config.js
+  useAgnosticPluginName,
+  agnostic20ConfigName,
+  directive21ConfigName,
+  enforceEffectiveDirectivesRuleName,
+  enforceCommentedDirectivesRuleName,
+} from "./_commons/constants/bases.js";

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "eslint-plugin-use-agnostic",
+  "version": "0.1.0",
+  "description": "eslint-plugin-use-agnostic highlights problematic server-client imports in projects made with the Fullstack React Architecture (Next.js App Router, etc.) based on each of their modules' derived effective directives through detailed import rule violations, thanks to the introduction of its very own 'use agnostic' directive.",
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "react",
+    "nextjs",
+    "next-js",
+    "remix",
+    "reactrouter",
+    "react-router"
+  ],
+  "license": "MIT",
+  "author": "Luther Tchofo Safo <luther@tchofo-safo-portfolio.me>",
+  "files": [
+    "library"
+  ],
+  "exports": {
+    ".": "./library/index.js"
+  },
+  "main": "library/index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LutherTS/eslint-plugin-use-agnostic.git"
+  },
+  "dependencies": {
+    "tsconfig-paths": "^4.2.0"
+  },
+  "devDependencies": {
+    "@typescript-eslint/utils": "^8.31.1",
+    "eslint": ">=9.0.0"
+  },
+  "peerDependencies": {
+    "eslint": ">=9.0.0"
+  },
+  "engines": {
+    "node": ">=18.18.0 <18.99 || >=20.9.0 <21.0.0 || >=21.1.0"
+  },
+  "type": "module"
+}