eslint-plugin-use-agnostic 1.6.8 → 1.6.10

package/library/directive21/_commons/utilities/flows.js

@@ -7,9 +7,11 @@ import {
   EXTENSIONS,
   reExportNotSameMessageId,
   importBreaksCommentedImportRulesMessageId,
-  noCommentedDirective,
-  commentedDirectiveVerificationFailed,
-  importNotStrategized,
+  noCommentedDirectiveMessageId,
+  commentedDirectiveVerificationFailedMessageId,
+  commentedDirectiveReactDirectiveFailedMessageId,
+  importNotStrategizedMessageId,
+  cantChainImportAcrossEnvironmentsMessageId,
   skip,
 } from "../../../_commons/constants/bases.js";
 import {
@@ -17,12 +19,20 @@ import {
   commentedDirectives_verificationReports,
   // currentFileCommentedDirective,
   // importedFileCommentedDirective,
+  // currentFileEnvironment,
+  // importedFileEnvironment,
   commentedDirectiveMessage,
   specificViolationMessage,
   specificFailure,
+  // verifiedCommentedDirective,
+  // expectedReactDirectiveAsText,
+  environments_allowedChainImportEnvironments,
+  commentedDirectives_reactDirectives,
+  reactDirectives_asTexts,
 } from "../constants/bases.js";
 
 import { highlightFirstLineOfCode } from "../../../_commons/utilities/helpers.js";
+import { getDirectiveFromCurrentModule } from "../../../agnostic20/_commons/utilities/helpers.js";
 import {
   getCommentedDirectiveFromCurrentModule,
   getVerifiedCommentedDirective,
@@ -33,6 +43,7 @@ import {
   getStrategizedDirective,
   addressDirectiveIfAgnosticStrategies,
 } from "./helpers.js";
+import { analyzeExportsForReExports } from "./analyze-exports-re.js";
 
 /**
  * @typedef {import('../../../../types/directive21/_commons/typedefs.js').Context} Context
@@ -41,14 +52,15 @@ import {
  * @typedef {import('../../../../types/directive21/_commons/typedefs.js').ExportNamedDeclaration} ExportNamedDeclaration
  * @typedef {import('../../../../types/directive21/_commons/typedefs.js').ExportAllDeclaration} ExportAllDeclaration
  * @typedef {import('../../../../types/directive21/_commons/typedefs.js').ExportDefaultDeclaration} ExportDefaultDeclaration
+ * @typedef {import('../../../../types/directive21/_commons/typedefs.js').Environment} Environment
  */
 
 /* currentFileFlow */
 
 /**
- * The flow that begins the import rules enforcement rule, retrieving the verified commented directive of the current file before comparing it to upcoming verified commented directives of the files it imports.
- * @param {Context} context The ESLint rule's `context` object.
- * @returns Either an object with `skip: true` to disregard or one with the non-null `verifiedCommentedDirective`.
+ * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#CURRENTFILEFLOW
+ * @param {Context} context $COMMENT#JSDOC#PARAMS#CONTEXTB
+ * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#CURRENTFILEFLOW
  */
 export const currentFileFlow = (context) => {
   const skipTrue = { ...skip, verifiedCommentedDirective: undefined };
@@ -74,7 +86,7 @@ export const currentFileFlow = (context) => {
   if (!commentedDirective) {
     context.report({
       loc: highlightFirstLineOfCode(context),
-      messageId: noCommentedDirective,
+      messageId: noCommentedDirectiveMessageId,
     });
     return skipTrue;
   }
@@ -89,7 +101,7 @@ export const currentFileFlow = (context) => {
   if (!verifiedCommentedDirective) {
     context.report({
       loc: highlightFirstLineOfCode(context),
-      messageId: commentedDirectiveVerificationFailed,
+      messageId: commentedDirectiveVerificationFailedMessageId,
       data: {
         [specificFailure]:
           commentedDirectives_verificationReports[commentedDirective],
@@ -98,19 +110,56 @@ export const currentFileFlow = (context) => {
     return skipTrue;
   }
 
+  // GETTING THE DIRECTIVE (or lack thereof) OF THE CURRENT FILE
+  const currentFileDirective = getDirectiveFromCurrentModule(context);
+
+  if (
+    commentedDirectives_reactDirectives[verifiedCommentedDirective] !==
+    currentFileDirective
+  ) {
+    const expectedReactDirective =
+      commentedDirectives_reactDirectives[verifiedCommentedDirective];
+    const expectedReactDirectiveAsText = reactDirectives_asTexts.get(
+      expectedReactDirective
+    );
+
+    if (!expectedReactDirectiveAsText) {
+      console.warn(
+        `Somehow, expectedReactDirectiveAsText for ${expectedReactDirective} is undefined.`
+      );
+      return { skip: undefined, verifiedCommentedDirective }; // at this time, behave as if the new implementation didn't exist yet
+    }
+
+    context.report({
+      loc: highlightFirstLineOfCode(context),
+      messageId: commentedDirectiveReactDirectiveFailedMessageId, // ADD NEW
+      data: {
+        // verifiedCommentedDirective
+        verifiedCommentedDirective,
+        // expectedReactDirectiveAsText
+        expectedReactDirectiveAsText,
+      },
+    });
+    return skipTrue;
+  }
+
   return { skip: undefined, verifiedCommentedDirective };
 };
 
 /* importedFileFlow */
 
 /**
- * The flow that is shared between import and re-export traversals to obtain the import file's commented directive.
- * @param {Context} context The ESLint rule's `context` object.
- * @param {ImportDeclaration} node The ESLint `node` of the rule's current traversal.
- * @returns Either an object with `skip: true` to disregard or one with the non-null `importedFileCommentedDirective`.
+ * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#IMPORTEDFILEFLOW
+ * @param {Context} context $COMMENT#JSDOC#PARAMS#CONTEXTB
+ * @param {ImportDeclaration} node $COMMENT#JSDOC#PARAMS#NODE
+ * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#IMPORTEDFILEFLOW (And now we the added results of `analyzeExportsForReExports`.)
  */
 const importedFileFlow = (context, node) => {
-  const skipTrue = { ...skip, importedFileCommentedDirective: undefined };
+  const skipTrue = {
+    ...skip,
+    importedFileCommentedDirective: undefined,
+    analyzeExportsForReExportsResults: undefined,
+  };
 
   // finds the full path of the import
   const resolvedImportPath = resolveImportingPath(
@@ -130,15 +179,17 @@ const importedFileFlow = (context, node) => {
   if (!isImportedFileJS) return skipTrue;
 
   // GETTING THE DIRECTIVE (or lack thereof) OF THE IMPORTED FILE
-  let importedFileCommentedDirective =
-    getCommentedDirectiveFromImportedModule(resolvedImportPath);
+  let {
+    commentedDirective: importedFileCommentedDirective,
+    sourceCode: importedFileSourceCode,
+  } = getCommentedDirectiveFromImportedModule(resolvedImportPath);
 
   // returns early if there is no directive or no valid directive (same, but eventually no directive could have defaults)
   if (!importedFileCommentedDirective) {
     // Now silencing the warning as superfluous, in order to not warn on imports of files without a commented directive that are outside of linting range.
 
     // console.warn(
-    //   `WARNING. The imported file ${resolvedImportPath}, whose path has been resolved from ${context.filename}, has no commented directive. It is thus ignored since the report on that circumstance would be available on the imported file itself.`
+    //   `WARNING. The imported file ${resolvedImportPath}, whose path has been resolved from ${context.filename}, has no commented $COMMENT#JSDOC#FORCOMPOSEDVARIABLES#DIRECTIVEPERIOD It is thus ignored since the report on that circumstance would be available on the imported file itself.`
     // ); // The decision not to report has been taken to not inflate the number of warnings.
     return skipTrue;
   }
@@ -160,7 +211,7 @@ const importedFileFlow = (context, node) => {
     if (importingFileCommentedDirective === null) {
       context.report({
         node,
-        messageId: importNotStrategized,
+        messageId: importNotStrategizedMessageId,
       });
       return skipTrue;
     }
@@ -169,17 +220,37 @@ const importedFileFlow = (context, node) => {
     importedFileCommentedDirective = importingFileCommentedDirective;
   }
 
-  return { skip: undefined, importedFileCommentedDirective };
+  // you never know
+  if (!importedFileSourceCode) {
+    console.warn(
+      `Somehow, file "${resolvedImportPath}" does not have a SourceCode object obtainable.`
+    );
+    return {
+      skip: undefined,
+      importedFileCommentedDirective,
+      analyzeExportsForReExportsResults: undefined,
+    };
+  }
+
+  const analyzeExportsForReExportsResults = analyzeExportsForReExports(
+    importedFileSourceCode
+  );
+
+  return {
+    skip: undefined,
+    importedFileCommentedDirective,
+    analyzeExportsForReExportsResults,
+  };
 };
 
 /* importsFlow */
 
 /**
- * The full flow for import traversals to enforce effective directives import rules.
- * @param {Context} context The ESLint rule's `context` object.
- * @param {ImportDeclaration} node The ESLint `node` of the rule's current traversal.
- * @param {CommentedDirective} currentFileCommentedDirective The current file's commented directive.
- * @returns Early if the flow needs to be interrupted.
+ * $COMMENT#JSDOC#FORALIASVARIABLES#IMPORTSFLOW
+ * @param {Context} context $COMMENT#JSDOC#PARAMS#CONTEXTB
+ * @param {ImportDeclaration} node $COMMENT#JSDOC#PARAMS#NODE
+ * @param {CommentedDirective} currentFileCommentedDirective $COMMENT#JSDOC#PARAMS#DIRECTIVE21#CURRENTFILECOMMENTEDDIRECTIVE
+ * @returns $COMMENT#JSDOC#FORALIASVARIABLES#FLOWRETURNSEARLY
  */
 export const importsFlow = (context, node, currentFileCommentedDirective) => {
   // does not operate on `import type`
@@ -214,22 +285,73 @@ export const importsFlow = (context, node, currentFileCommentedDirective) => {
       },
     });
   }
+
+  // new
+  if (result.analyzeExportsForReExportsResults) {
+    const { reExportsWithSource, reExportsViaLocal } =
+      result.analyzeExportsForReExportsResults;
+    // console.debug("reExportsWithSource are:", reExportsWithSource);
+    // console.debug("reExportsViaLocal are:", reExportsViaLocal);
+    // console.debug(
+    //   "currentFileCommentedDirective is:",
+    //   currentFileCommentedDirective
+    // );
+    // console.debug(
+    //   "importedFileCommentedDirective is:",
+    //   importedFileCommentedDirective
+    // );
+    // console.debug(context.sourceCode.getText(node));
+
+    // immediately returns if no re-exports are found
+    if (reExportsWithSource.length === 0 && reExportsViaLocal.length === 0)
+      return;
+
+    /** @type {Environment} */
+    const currentFileEnvironment = currentFileCommentedDirective.split(" ")[1];
+    /** @type {Environment} */
+    const importedFileEnvironment =
+      importedFileCommentedDirective.split(" ")[1];
+    // console.debug("currentFileEnvironment is:", currentFileEnvironment);
+    // console.debug("importedFileEnvironment is:", importedFileEnvironment);
+
+    if (
+      !environments_allowedChainImportEnvironments[
+        currentFileEnvironment
+      ].includes(importedFileEnvironment)
+    ) {
+      // console.debug(cantChainImportAcrossEnvironmentsMessageId);
+
+      context.report({
+        node,
+        messageId: cantChainImportAcrossEnvironmentsMessageId,
+        data: {
+          // currentFileEnvironment:
+          currentFileEnvironment,
+          // importedFileEnvironment:
+          importedFileEnvironment,
+        },
+      });
+    }
+  }
 };
 
 /* 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 {Context} context The ESLint rule's `context` object.
- * @param {ExportNamedDeclaration | ExportAllDeclaration | ExportDefaultDeclaration} node The ESLint `node` of the rule's current traversal.
- * @param {CommentedDirective} currentFileCommentedDirective The current file's commented directive.
- * @returns Early if the flow needs to be interrupted.
+ * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#ALLEXPORTSFLOW
+ * @param {Context} context $COMMENT#JSDOC#PARAMS#CONTEXTB
+ * @param {ExportNamedDeclaration | ExportAllDeclaration | ExportDefaultDeclaration} node $COMMENT#JSDOC#PARAMS#NODE
+ * @param {CommentedDirective} currentFileCommentedDirective $COMMENT#JSDOC#PARAMS#DIRECTIVE21#CURRENTFILECOMMENTEDDIRECTIVE
+ * @returns $COMMENT#JSDOC#FORALIASVARIABLES#FLOWRETURNSEARLY
  */
 export const allExportsFlow = (
   context,
   node,
   currentFileCommentedDirective
 ) => {
+  // saving the original commented directive (speficially for "use agnostic strategies")
+  const originalCurrentFileCommentedDirective = currentFileCommentedDirective;
+
   // does not operate on `export type`
   if (node.exportKind === "type") return;
 
@@ -271,5 +393,56 @@ export const allExportsFlow = (
         },
       });
     }
+
+    // new
+    if (result.analyzeExportsForReExportsResults) {
+      const { reExportsWithSource, reExportsViaLocal } =
+        result.analyzeExportsForReExportsResults;
+      // console.debug("reExportsWithSource are:", reExportsWithSource);
+      // console.debug("reExportsViaLocal are:", reExportsViaLocal);
+      // console.debug(
+      //   "currentFileCommentedDirective is:",
+      //   currentFileCommentedDirective
+      // );
+      // console.debug(
+      //   "importedFileCommentedDirective is:",
+      //   importedFileCommentedDirective
+      // );
+      // console.debug(context.sourceCode.getText(node));
+
+      // immediately returns if no re-exports are found
+      if (reExportsWithSource.length === 0 && reExportsViaLocal.length === 0)
+        return;
+
+      if (originalCurrentFileCommentedDirective !== USE_AGNOSTIC_STRATEGIES) {
+        /** @type {Environment} */
+        const currentFileEnvironment =
+          currentFileCommentedDirective.split(" ")[1];
+        /** @type {Environment} */
+        const importedFileEnvironment =
+          importedFileCommentedDirective.split(" ")[1];
+        // console.debug("currentFileEnvironment is:", currentFileEnvironment);
+        // console.debug("importedFileEnvironment is:", importedFileEnvironment);
+
+        if (
+          !environments_allowedChainImportEnvironments[
+            currentFileEnvironment
+          ].includes(importedFileEnvironment)
+        ) {
+          // console.debug(cantChainImportAcrossEnvironmentsMessageId);
+
+          context.report({
+            node,
+            messageId: cantChainImportAcrossEnvironmentsMessageId,
+            data: {
+              // currentFileEnvironment:
+              currentFileEnvironment,
+              // importedFileEnvironment:
+              importedFileEnvironment,
+            },
+          });
+        }
+      }
+    }
   }
 };

package/library/directive21/_commons/utilities/helpers.js

@@ -1,6 +1,6 @@
 import { getSourceCodeFromFilePath } from "get-sourcecode-from-file-path";
 
-import { exportNotStrategized } from "../../../_commons/constants/bases.js";
+import { exportNotStrategizedMessageId } from "../../../_commons/constants/bases.js";
 import {
   USE_AGNOSTIC_STRATEGIES,
   commentedDirectivesArray,
@@ -31,9 +31,9 @@ import {
 /* getCommentedDirectiveFromSourceCode */
 
 /**
- * Detects whether a string is single- or double-quoted.
- * @param {string} string The original string.
- * @returns `true` if single-quoted, `false` if double-quoted, `null` if neither.
+ * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#DETECTQUOTETYPE
+ * @param {string} string $COMMENT#JSDOC#PARAMS#DIRECTIVE21#STRING
+ * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#DETECTQUOTETYPE
  */
 const detectQuoteType = (string) => {
   if (string.startsWith("'") && string.endsWith("'")) {
@@ -46,9 +46,9 @@ const detectQuoteType = (string) => {
 };
 
 /**
- * Removes single quotes from a string known to be single-quoted.
- * @param {string} string The original string.
- * @returns The string with quotes removed.
+ * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#STRIPSINGLEQUOTES
+ * @param {string} string $COMMENT#JSDOC#PARAMS#DIRECTIVE21#STRING
+ * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#STRIPSINGLEQUOTES
  */
 const stripSingleQuotes = (string) => {
   if (string.startsWith("'") && string.endsWith("'")) {
@@ -58,9 +58,9 @@ const stripSingleQuotes = (string) => {
 };
 
 /**
- * Removes double quotes from a string known to be double-quoted.
- * @param {string} string The original string.
- * @returns The string with quotes removed.
+ * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#STRIPDOUBLEQUOTES
+ * @param {string} string $COMMENT#JSDOC#PARAMS#DIRECTIVE21#STRING
+ * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#STRIPSINGLEQUOTES
  */
 const stripDoubleQuotes = (string) => {
   if (string.startsWith('"') && string.endsWith('"')) {
@@ -70,21 +70,21 @@ const stripDoubleQuotes = (string) => {
 };
 
 /**
- * Gets the commented directive of a module from its ESLint `SourceCode` object.
+ * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#GETCOMMENTEDDIRECTIVEFROMSOURCECODE1
  *
- * 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 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 {SourceCode} sourceCode The ESLint SourceCode object.
- * @returns 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 become provided.)
+ * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#GETCOMMENTEDDIRECTIVEFROMSOURCECODE2
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USESERVERLOGICSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USECLIENTLOGICSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USEAGNOSTICLOGICSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USESERVERCOMPONENTSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USECLIENTCOMPONENTSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USEAGNOSTICCOMPONENTSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USESERVERFUNCTIONSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USECLIENTCONTEXTSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USEAGNOSTICCONDITIONSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USEAGNOSTICSTRATEGIESA
+ * @param {SourceCode} sourceCode $COMMENT#JSDOC#PARAMS#DIRECTIVE21#SOURCECODE
+ * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#GETCOMMENTEDDIRECTIVEFROMSOURCECODE
  */
 export const getCommentedDirectiveFromSourceCode = (sourceCode) => {
   // gets all comments from the source code
@@ -132,21 +132,21 @@ export const getCommentedDirectiveFromSourceCode = (sourceCode) => {
 /* getCommentedDirectiveFromCurrentModule */
 
 /**
- * Gets the commented directive of the current module.
+ * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#GETCOMMENTEDDIRECTIVEFROMCURRENTMODULE1
  *
- * 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 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 {Context} context The ESLint rule's `context` object.
- * @returns 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 become provided.)
+ * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#GETCOMMENTEDDIRECTIVEFROMSOURCECODE2
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USESERVERLOGICSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USECLIENTLOGICSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USEAGNOSTICLOGICSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USESERVERCOMPONENTSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USECLIENTCOMPONENTSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USEAGNOSTICCOMPONENTSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USESERVERFUNCTIONSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USECLIENTCONTEXTSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USEAGNOSTICCONDITIONSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USEAGNOSTICSTRATEGIESA
+ * @param {Context} context $COMMENT#JSDOC#PARAMS#CONTEXTB
+ * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#GETCOMMENTEDDIRECTIVEFROMSOURCECODE
  */
 export const getCommentedDirectiveFromCurrentModule = (context) => {
   const sourceCode = context.sourceCode;
@@ -158,46 +158,46 @@ export const getCommentedDirectiveFromCurrentModule = (context) => {
 /* getCommentedDirectiveFromImportedModule */
 
 /**
- * Gets the commented directive of the imported module.
+ * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#GETCOMMENTEDDIRECTIVEFROMIMPORTEDMODULE1
  *
- * 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 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} resolvedPath The resolved path of the imported module.
- * @returns 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 become provided.)
+ * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#GETCOMMENTEDDIRECTIVEFROMSOURCECODE2
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USESERVERLOGICSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USECLIENTLOGICSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USEAGNOSTICLOGICSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USESERVERCOMPONENTSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USECLIENTCOMPONENTSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USEAGNOSTICCOMPONENTSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USESERVERFUNCTIONSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USECLIENTCONTEXTSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USEAGNOSTICCONDITIONSA
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USEAGNOSTICSTRATEGIESA
+ * @param {string} resolvedPath $COMMENT#JSDOC#PARAMS#RESOLVEDPATH
+ * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#GETCOMMENTEDDIRECTIVEFROMSOURCECODE Now also provides the obtained SourceCode object.
  */
 export const getCommentedDirectiveFromImportedModule = (resolvedPath) => {
   const sourceCode = getSourceCodeFromFilePath(resolvedPath);
   const commentedDirective = getCommentedDirectiveFromSourceCode(sourceCode);
 
-  return commentedDirective;
+  return { commentedDirective, sourceCode };
 };
 
 /* 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 {CommentedDirective} directive The commented directive as written on top of the file (cannot be `null` at that stage).
- * @param {Extension} extension The JavaScript (TypeScript) extension of the file.
- * @returns 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.
+ * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#GETVERIFIEDCOMMENTEDDIRECTIVE
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USESERVERLOGICSB
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USECLIENTLOGICSB
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USEAGNOSTICLOGICSB
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USESERVERCOMPONENTSB
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USECLIENTCOMPONENTSB
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USEAGNOSTICCOMPONENTSB
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USESERVERFUNCTIONSB
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USECLIENTCONTEXTSB
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USEAGNOSTICCONDITIONSB
+ * - $COMMENT#JSDOC#DETAILS#DIRECTIVE21#USEAGNOSTICSTRATEGIESB
+ * @param {CommentedDirective} directive $COMMENT#JSDOC#PARAMS#DIRECTIVE21#DIRECTIVE
+ * @param {Extension} extension $COMMENT#JSDOC#PARAMS#EXTENSION
+ * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#GETVERIFIEDCOMMENTEDDIRECTIVE
  */
 export const getVerifiedCommentedDirective = (directive, extension) => {
   const rule = commentedDirectives_extensionRules[directive];
@@ -214,10 +214,10 @@ export const getVerifiedCommentedDirective = (directive, extension) => {
 /* getStrategizedDirective */
 
 /**
- * Gets the interpreted directive from a specified commented Strategy (such as `@serverLogics`) nested inside the import (or export) declaration for an import (or export) from an Agnostic Strategies Module.
- * @param {Context} context The ESLint rule's `context` object.
- * @param {ImportDeclaration | ExportNamedDeclaration | ExportAllDeclaration | ExportDefaultDeclaration} node The ESLint `node` of the rule's current traversal.
- * @returns The interpreted directive, a.k.a. strategized directive, or lack thereof via `null`.
+ * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#GETSTRATEGIZEDDIRECTIVE
+ * @param {Context} context $COMMENT#JSDOC#PARAMS#CONTEXTB
+ * @param {ImportDeclaration | ExportNamedDeclaration | ExportAllDeclaration | ExportDefaultDeclaration} node $COMMENT#JSDOC#PARAMS#NODE
+ * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#GETSTRATEGIZEDDIRECTIVE
  */
 export const getStrategizedDirective = (context, node) => {
   // gets the first nested `/* */` comment inside the node
@@ -246,11 +246,11 @@ export const getStrategizedDirective = (context, node) => {
 /* addressDirectiveIfAgnosticStrategies */
 
 /**
- * Verifies the current node's export strategy if the current commented directive is `"use agnostic strategies"` by reporting `exportNotStrategized` in case an export is not strategized in an Agnostic Strategies Module.
- * @param {Context} context The ESLint rule's `context` object.
- * @param {ExportNamedDeclaration | ExportAllDeclaration | ExportDefaultDeclaration} node The ESLint `node` of the rule's current traversal.
- * @param {CommentedDirective} currentFileCommentedDirective The current file's commented directive.
- * @returns The commented directive, the addressed strategy (as a commented directive) or `null` in case of failure.
+ * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#ADDRESSDIRECTIVEIFAGNOSTICSTRATEGIES
+ * @param {Context} context $COMMENT#JSDOC#PARAMS#CONTEXTB
+ * @param {ExportNamedDeclaration | ExportAllDeclaration | ExportDefaultDeclaration} node $COMMENT#JSDOC#PARAMS#NODE
+ * @param {CommentedDirective} currentFileCommentedDirective $COMMENT#JSDOC#PARAMS#DIRECTIVE21#CURRENTFILECOMMENTEDDIRECTIVE
+ * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#ADDRESSDIRECTIVEIFAGNOSTICSTRATEGIES
  */
 export const addressDirectiveIfAgnosticStrategies = (
   context,
@@ -266,7 +266,7 @@ export const addressDirectiveIfAgnosticStrategies = (
   if (exportStrategizedDirective === null) {
     context.report({
       node,
-      messageId: exportNotStrategized,
+      messageId: exportNotStrategizedMessageId,
     });
   }
 
@@ -276,10 +276,10 @@ export const addressDirectiveIfAgnosticStrategies = (
 /* isImportBlocked */
 
 /**
- * Returns a boolean deciding if an imported file's commented directive is incompatible with the current file's commented directive.
- * @param {CommentedDirectiveWithoutUseAgnosticStrategies} currentFileCommentedDirective The current file's commented directive.
- * @param {CommentedDirectiveWithoutUseAgnosticStrategies} importedFileCommentedDirective The imported file's commented directive.
- * @returns `true` if the import is blocked, as established in `commentedDirectives_BlockedImports`.
+ * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#ISIMPORTBLOCKED
+ * @param {CommentedDirectiveWithoutUseAgnosticStrategies} currentFileCommentedDirective $COMMENT#JSDOC#PARAMS#DIRECTIVE21#CURRENTFILECOMMENTEDDIRECTIVE
+ * @param {CommentedDirectiveWithoutUseAgnosticStrategies} importedFileCommentedDirective $COMMENT#JSDOC#PARAMS#DIRECTIVE21#IMPORTEDFILECOMMENTEDDIRECTIVE
+ * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#ISIMPORTBLOCKED
  */
 export const isImportBlocked = (
   currentFileCommentedDirective,
@@ -294,9 +294,9 @@ export const isImportBlocked = (
 /* makeMessageFromCurrentFileCommentedDirective */
 
 /**
- * Lists in an message the commented modules incompatible with a commented module based on its commented directive.
- * @param {CommentedDirectiveWithoutUseAgnosticStrategies} commentedDirective The commented directive of the commented module.
- * @returns The message listing the incompatible commented modules.
+ * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#MAKEMESSAGEFROMCURRENTFILECOMMENTEDDIRECTIVE
+ * @param {CommentedDirectiveWithoutUseAgnosticStrategies} commentedDirective $COMMENT#JSDOC#PARAMS#DIRECTIVE21#COMMENTEDDIRECTIVE
+ * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#MAKEMESSAGEFROMCURRENTFILECOMMENTEDDIRECTIVE
  */
 export const makeMessageFromCurrentFileCommentedDirective = (
   commentedDirective
@@ -309,10 +309,10 @@ export const makeMessageFromCurrentFileCommentedDirective = (
 /* findSpecificViolationMessage */
 
 /**
- * Finds the `message` for the specific violation of commented directives import rules based on `commentedDirectives_BlockedImports`.
- * @param {CommentedDirectiveWithoutUseAgnosticStrategies} currentFileCommentedDirective The current file's commented directive.
- * @param {CommentedDirectiveWithoutUseAgnosticStrategies} importedFileCommentedDirective The imported file's commented directive.
- * @returns The corresponding `message`.
+ * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#FINDSPECIFICVIOLATIONMESSAGE
+ * @param {CommentedDirectiveWithoutUseAgnosticStrategies} currentFileCommentedDirective $COMMENT#JSDOC#PARAMS#DIRECTIVE21#CURRENTFILECOMMENTEDDIRECTIVE
+ * @param {CommentedDirectiveWithoutUseAgnosticStrategies} importedFileCommentedDirective $COMMENT#JSDOC#PARAMS#DIRECTIVE21#IMPORTEDFILECOMMENTEDDIRECTIVE
+ * @returns $COMMENT#JSDOC#RETURNS#FINDSPECIFICVIOLATIONMESSAGE
  */
 export const findSpecificViolationMessage = (
   currentFileCommentedDirective,

package/library/directive21/config.js

@@ -12,9 +12,9 @@ import {
  */
 
 /**
- * Makes the directive21 config for the use-agnostic ESLint plugin.
- * @param {Plugin} plugin The use-agnostic ESLint plugin itself.
- * @returns The directive21 config's name as a key and its config as its value.
+ * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#MAKEDIRECTIVE21CONFIG
+ * @param {Plugin} plugin $COMMENT#JSDOC#PARAMS#PLUGIN
+ * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#MAKEDIRECTIVE21CONFIG
  */
 export const makeDirective21Config = (plugin) => ({
   [directive21ConfigName]: defineConfig([

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-use-agnostic",
-  "version": "1.6.8",
+  "version": "1.6.10",
   "description": "Highlights problematic server-client imports in projects made with the Fullstack React Architecture.",
   "keywords": [
     "eslint",
@@ -44,7 +44,7 @@
   },
   "dependencies": {
     "find-up": "^8.0.0",
-    "get-sourcecode-from-file-path": "^1.1.2",
+    "get-sourcecode-from-file-path": "^1.1.3",
     "resolve-importing-path": "^1.0.3",
     "typescript-eslint": "^8.32.0"
   },