eslint-plugin-use-agnostic 2.0.8 → 2.1.0

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

@@ -1,8 +1,5 @@
 import path from "path";
 
-import { resolveImportingPath } from "resolve-importing-path";
-import { findUpSync } from "find-up";
-
 import {
   EXTENSIONS,
   reExportNotSameMessageId,
@@ -134,9 +131,9 @@ export const fileIsRegularJavaScript = (filePath) =>
 //
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#CURRENTFILEFLOW
- * @param {Context} context $COMMENT#JSDOC#PARAMS#CONTEXTB
- * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#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`.
  */
 export const currentFileFlow = (context) => {
   const skipTrue = { ...skip, verifiedCommentedDirective: undefined };
@@ -232,11 +229,11 @@ export const currentFileFlow = (context) => {
 /* importedFileFlow */
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#IMPORTEDFILEFLOW
- * @param {Context} context $COMMENT#JSDOC#PARAMS#CONTEXTB
- * @param {ImportDeclaration} node $COMMENT#JSDOC#PARAMS#NODE
- * @param {ResolverFactory} resolver
- * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#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.
+ * @param {ResolverFactory} resolver The resolver generated with `oxc-resolver` to resolve the node's import path.
+ * @returns Either an object with `skip: true` to disregard or one with the non-null `importedFileCommentedDirective`. And now with the added results of `analyzeExportsForReExports`.
  */
 const importedFileFlow = (context, node, resolver) => {
   const skipTrue = {
@@ -246,18 +243,8 @@ const importedFileFlow = (context, node, resolver) => {
   };
 
   // finds the full path of the import
-  // const resolvedImportPath = resolveImportingPath(
-  //   path.dirname(context.filename),
-  //   node.source.value,
-  //   findUpSync("tsconfig.json", {
-  //     cwd: path.dirname(context.filename),
-  //   }) ?? context.cwd,
-  // );
-  const resolvedImportPath = resolver.resolveFileSync(
-    context.filename,
-    node.source.value,
-  ).path;
-  console.debug("resolvedImportPath is:", resolvedImportPath);
+  const resolvedImportPath =
+    resolver.resolveFileSync(context.filename, node.source.value).path ?? null; // works
 
   // does not operate on paths it did not resolve
   if (resolvedImportPath === null) return skipTrue;
@@ -272,13 +259,14 @@ const importedFileFlow = (context, node, resolver) => {
     commentedDirective: importedFileCommentedDirective,
     sourceCode: importedFileSourceCode,
   } = getCommentedDirectiveFromImportedModule(resolvedImportPath);
+  // Actually, this will need to remain, because the obtained `importedFileSourceCode` is necessary for further linting.
 
   // 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 $COMMENT#JSDOC#FORCOMPOSEDVARIABLES#DIRECTIVEPERIOD 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 directive. 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;
   }
@@ -340,11 +328,11 @@ const importedFileFlow = (context, node, resolver) => {
 
 // NEW!! Currently strictly adapted from importedFileFlow
 /**
- * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#IMPORTEDFILEFLOWREQUIRE
- * @param {Context} context $COMMENT#JSDOC#PARAMS#CONTEXTB
- * @param {CallExpression} node $COMMENT#JSDOC#PARAMS#NODE
- * @param {ResolverFactory} resolver
- * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#IMPORTEDFILEFLOW
+ * The `importedFileFlow` adapted for `require` calls to obtain the import file's commented directive.
+ * @param {Context} context The ESLint rule's `context` object.
+ * @param {CallExpression} node The ESLint `node` of the rule's current traversal.
+ * @param {ResolverFactory} resolver The resolver generated with `oxc-resolver` to resolve the node's import path.
+ * @returns Either an object with `skip: true` to disregard or one with the non-null `importedFileCommentedDirective`. And now with the added results of `analyzeExportsForReExports`.
  */
 const importedFileFlowRequire = (context, node, resolver) => {
   const skipTrue = {
@@ -364,18 +352,8 @@ const importedFileFlowRequire = (context, node, resolver) => {
     if (typeof importPath !== "string") return skipTrue;
 
     // finds the full path of the import
-    // const resolvedImportPath = resolveImportingPath(
-    //   path.dirname(context.filename),
-    //   importPath,
-    //   findUpSync("tsconfig.json", {
-    //     cwd: path.dirname(context.filename),
-    //   }) ?? context.cwd,
-    // );
-    const resolvedImportPath = resolver.resolveFileSync(
-      context.filename,
-      importPath,
-    ).path;
-    console.debug("resolvedImportPath (require) is:", resolvedImportPath);
+    const resolvedImportPath =
+      resolver.resolveFileSync(context.filename, importPath).path ?? null; // works (?)
 
     // does not operate on paths it did not resolve
     if (resolvedImportPath === null) return skipTrue;
@@ -396,7 +374,7 @@ const importedFileFlowRequire = (context, node, resolver) => {
       // 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 $COMMENT#JSDOC#FORCOMPOSEDVARIABLES#DIRECTIVEPERIOD 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 directive. 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;
     }
@@ -457,12 +435,12 @@ const importedFileFlowRequire = (context, node, resolver) => {
 /* importsFlow */
 
 /**
- * $COMMENT#JSDOC#FORALIASVARIABLES#IMPORTSFLOWCOMMENTED
- * @param {Context} context $COMMENT#JSDOC#PARAMS#CONTEXTB
- * @param {ImportDeclaration} node $COMMENT#JSDOC#PARAMS#NODE
- * @param {CommentedDirective} currentFileCommentedDirective $COMMENT#JSDOC#PARAMS#DIRECTIVE21#CURRENTFILECOMMENTEDDIRECTIVE
- * @param {ResolverFactory} resolver
- * @returns $COMMENT#JSDOC#FORALIASVARIABLES#FLOWRETURNSEARLY
+ * The full flow for import traversals to enforce commented 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.
+ * @param {ResolverFactory} resolver The resolver generated with `oxc-resolver` to resolve the node's import path.
+ * @returns Early if the flow needs to be interrupted.
  */
 export const importsFlow = (
   context,
@@ -540,12 +518,12 @@ export const importsFlow = (
 
 // NEW!! Currently strictly adapted from importsFlow
 /**
- * $COMMENT#JSDOC#FORALIASVARIABLES#IMPORTSFLOWCOMMENTEDREQUIRE
- * @param {Context} context $COMMENT#JSDOC#PARAMS#CONTEXTB
- * @param {CallExpression} node $COMMENT#JSDOC#PARAMS#NODE
- * @param {CommentedDirective} currentFileCommentedDirective $COMMENT#JSDOC#PARAMS#DIRECTIVE21#CURRENTFILECOMMENTEDDIRECTIVE
- * @param {ResolverFactory} resolver
- * @returns $COMMENT#JSDOC#FORALIASVARIABLES#FLOWRETURNSEARLY
+ * The `importsFlow` adapted for `require` calls to enforce commented directives import rules.
+ * @param {Context} context The ESLint rule's `context` object.
+ * @param {CallExpression} node The ESLint `node` of the rule's current traversal.
+ * @param {CommentedDirective} currentFileCommentedDirective The current file's commented directive.
+ * @param {ResolverFactory} resolver The resolver generated with `oxc-resolver` to resolve the node's import path.
+ * @returns Early if the flow needs to be interrupted.
  */
 export const importsFlowRequire = (
   context,
@@ -621,12 +599,12 @@ export const importsFlowRequire = (
 /* allExportsFlow */
 
 /**
- * $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
- * @param {ResolverFactory} resolver
- * @returns $COMMENT#JSDOC#FORALIASVARIABLES#FLOWRETURNSEARLY
+ * 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.
+ * @param {ResolverFactory} resolver The resolver generated with `oxc-resolver` to resolve the node's import path.
+ * @returns Early if the flow needs to be interrupted.
  */
 export const allExportsFlow = (
   context,
@@ -667,12 +645,12 @@ export const allExportsFlow = (
     // else
     currentFileCommentedDirective = addressedDirective; // to still keep compatibility with strategies
 
-    // Lints imports of Agnostic Strategies Modules beyond strategy resolution, such as to warn imports of Special Agnostic Modules. Does the same with $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#KINDSSIMPLE Modules, since they are the only other modules which cannot import themselves.
+    // Lints imports of Agnostic Strategies Modules beyond strategy resolution, such as to warn imports of Special Agnostic Modules. Does the same with Agnostic Conditions Modules, since they are the only other modules which cannot import themselves.
     if (
       currentFileCommentedDirective === USE_AGNOSTIC_STRATEGIES ||
       currentFileCommentedDirective === USE_AGNOSTIC_CONDITIONS
     ) {
-      // Basically, all modules need to do reexports that correspond to their own modules, but not Agnostic Strategies Modules and $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#KINDSSIMPLE Modules, the latter which are in fact NOT allowed to do re-exports.
+      // Basically, all modules need to do reexports that correspond to their own modules, but not Agnostic Strategies Modules and Agnostic Conditions Modules, the latter which are in fact NOT allowed to do re-exports.
       if (
         isImportBlocked(
           currentFileCommentedDirective,
@@ -750,9 +728,9 @@ export const allExportsFlow = (
 /* functionDeclarationFlow */
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#NAMEISPASCALCASE
- * @param {string} name $COMMENT#JSDOC#PARAMS#DIRECTIVE21#NAME
- * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#NAMEISPASCALCASE
+ * Checks if the name of an identifier is in PascalCase, as a cheap way to assess whether or not it is a React component.
+ * @param {string} name The name of the identifier at hand.
+ * @returns `true` if the name is recognized as PascalCase, `false` otherwise.
  */
 const nameIsPascalCase = (name) => {
   // PascalCase: starts with capital, no underscores, no hyphens
@@ -760,9 +738,9 @@ const nameIsPascalCase = (name) => {
 };
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#DECLARESCHILDRENPROP
- * @param {Parameter[]} params $COMMENT#JSDOC#PARAMS#DIRECTIVE21#PARAMS
- * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#DECLARESCHILDRENPROP
+ * Checks whether the parameters of a function (React component) include the `children` property.
+ * @param {Parameter[]} params The parameters at hand.
+ * @returns `true` if the parameters include the `children` property, `false` otherwise.
  */
 const declaresChildrenProp = (params) => {
   if (params.length === 0) return false;
@@ -783,11 +761,11 @@ const declaresChildrenProp = (params) => {
 };
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#FUNCTIONDECLARATIONFLOW
- * @param {Context} context $COMMENT#JSDOC#PARAMS#CONTEXTB
- * @param {FunctionDeclaration} node $COMMENT#JSDOC#PARAMS#NODE
- * @param {CommentedDirective} currentFileCommentedDirective $COMMENT#JSDOC#PARAMS#DIRECTIVE21#CURRENTFILECOMMENTEDDIRECTIVE
- * @returns $COMMENT#JSDOC#FORALIASVARIABLES#FLOWRETURNSEARLY
+ * The flow for function declarations to ensure that Client Lineals Components are made in Client Components Modules and Client Contexts Components are made in Client Contexts Modules, based on the fact that the former are child-free and the latter are children-bearing.
+ * @param {Context} context The ESLint rule's `context` object.
+ * @param {FunctionDeclaration} 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.
  */
 export const functionDeclarationFlow = (
   context,
@@ -829,11 +807,11 @@ export const functionDeclarationFlow = (
 /* jsxElementFlow */
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#JSXELEMENTFLOW
- * @param {Context} context $COMMENT#JSDOC#PARAMS#CONTEXTB
- * @param {JSXElement} node $COMMENT#JSDOC#PARAMS#NODE
- * @param {CommentedDirective} currentFileCommentedDirective $COMMENT#JSDOC#PARAMS#DIRECTIVE21#CURRENTFILECOMMENTEDDIRECTIVE
- * @returns $COMMENT#JSDOC#FORALIASVARIABLES#FLOWRETURNSEARLY
+ * The flow for JSX elements to ensure that render props are only used isolated inside a Client Components Module, where their execution would safely be happening exclusively on the client.
+ * @param {Context} context The ESLint rule's `context` object.
+ * @param {JSXElement} 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.
  */
 export const jsxElementFlow = (
   context,
@@ -864,11 +842,11 @@ export const jsxElementFlow = (
 /* jsxOpeningElementFlow */
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#JSXOPENINGELEMENTFLOW
- * @param {Context} context $COMMENT#JSDOC#PARAMS#CONTEXTB
- * @param {JSXOpeningElement} node $COMMENT#JSDOC#PARAMS#NODE
- * @param {CommentedDirective} currentFileCommentedDirective $COMMENT#JSDOC#PARAMS#DIRECTIVE21#CURRENTFILECOMMENTEDDIRECTIVE
- * @returns $COMMENT#JSDOC#FORALIASVARIABLES#FLOWRETURNSEARLY
+ * The flow for JSX opening elements to ensure that event handler props on intrinsic elements are only used in modules that can safely create Client Components.
+ * @param {Context} context The ESLint rule's `context` object.
+ * @param {JSXOpeningElement} 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.
  */
 export const jsxOpeningElementFlow = (
   context,

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

@@ -30,9 +30,9 @@ import {
 /* getCommentedDirectiveFromSourceCode */
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#DETECTQUOTETYPE
- * @param {string} string $COMMENT#JSDOC#PARAMS#DIRECTIVE21#STRING
- * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#DETECTQUOTETYPE
+ * 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.
  */
 const detectQuoteType = (string) => {
   if (string.startsWith("'") && string.endsWith("'")) {
@@ -45,9 +45,9 @@ const detectQuoteType = (string) => {
 };
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#STRIPSINGLEQUOTES
- * @param {string} string $COMMENT#JSDOC#PARAMS#DIRECTIVE21#STRING
- * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#STRIPSINGLEQUOTES
+ * Removes single quotes from a string known to be single-quoted.
+ * @param {string} string The original string.
+ * @returns The string with quotes removed.
  */
 const stripSingleQuotes = (string) => {
   if (string.startsWith("'") && string.endsWith("'")) {
@@ -57,9 +57,9 @@ const stripSingleQuotes = (string) => {
 };
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#STRIPDOUBLEQUOTES
- * @param {string} string $COMMENT#JSDOC#PARAMS#DIRECTIVE21#STRING
- * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#STRIPSINGLEQUOTES
+ * Removes double quotes from a string known to be double-quoted.
+ * @param {string} string The original string.
+ * @returns The string with quotes removed.
  */
 const stripDoubleQuotes = (string) => {
   if (string.startsWith('"') && string.endsWith('"')) {
@@ -69,21 +69,21 @@ const stripDoubleQuotes = (string) => {
 };
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#GETCOMMENTEDDIRECTIVEFROMSOURCECODE1
+ * Gets the commented directive of a module from its ESLint `SourceCode` object.
  *
- * $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
+ * 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.)
  */
 export const getCommentedDirectiveFromSourceCode = (sourceCode) => {
   // returns null IMMEDIATELY if the SourceCode is faulty (inexistent)
@@ -134,21 +134,21 @@ export const getCommentedDirectiveFromSourceCode = (sourceCode) => {
 /* getCommentedDirectiveFromCurrentModule */
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#GETCOMMENTEDDIRECTIVEFROMCURRENTMODULE1
+ * Gets the commented directive of the current module.
  *
- * $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
+ * 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.)
  */
 export const getCommentedDirectiveFromCurrentModule = (context) => {
   const sourceCode = context.sourceCode;
@@ -163,21 +163,21 @@ export const getCommentedDirectiveFromCurrentModule = (context) => {
 /* getCommentedDirectiveFromImportedModule */
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#GETCOMMENTEDDIRECTIVEFROMIMPORTEDMODULE1
+ * Gets the commented directive of the imported module.
  *
- * $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#GETCOMMENTEDDIRECTIVEFROMIMPORTEDMODULE
+ * 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`. Now also provides the obtained `SourceCode` object. 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.)
  */
 export const getCommentedDirectiveFromImportedModule = (resolvedPath) => {
   const sourceCode = getSourceCodeFromFilePath(resolvedPath);
@@ -192,20 +192,20 @@ export const getCommentedDirectiveFromImportedModule = (resolvedPath) => {
 /* getVerifiedCommentedDirective */
 
 /**
- * $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
+ * 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.
  */
 export const getVerifiedCommentedDirective = (directive, extension) => {
   const rule = commentedDirectives_extensionRules[directive];
@@ -222,10 +222,10 @@ export const getVerifiedCommentedDirective = (directive, extension) => {
 /* getStrategizedDirective */
 
 /**
- * $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
+ * 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`.
  */
 export const getStrategizedDirective = (context, node) => {
   // gets the first nested `/* */` comment inside the node
@@ -314,11 +314,11 @@ export const fileIsRegularJavaScript = (filePath) =>
 //
 
 /**
- * $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
+ * 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.
  */
 export const addressDirectiveIfAgnosticStrategies = (
   context,
@@ -352,10 +352,10 @@ export const addressDirectiveIfAgnosticStrategies = (
 /* isImportBlocked */
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#ISIMPORTBLOCKED
- * @param {CommentedDirective} currentFileCommentedDirective $COMMENT#JSDOC#PARAMS#DIRECTIVE21#CURRENTFILECOMMENTEDDIRECTIVE
- * @param {CommentedDirective} importedFileCommentedDirective $COMMENT#JSDOC#PARAMS#DIRECTIVE21#IMPORTEDFILECOMMENTEDDIRECTIVE
- * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#ISIMPORTBLOCKED
+ * Returns a boolean deciding if an imported file's commented directive is incompatible with the current file's commented directive.
+ * @param {CommentedDirective} currentFileCommentedDirective The current file's commented directive.
+ * @param {CommentedDirective} importedFileCommentedDirective The imported file's commented directive.
+ * @returns `true` if the import is blocked, as established in `commentedDirectives_BlockedImports`.
  */
 export const isImportBlocked = (
   currentFileCommentedDirective,
@@ -370,9 +370,9 @@ export const isImportBlocked = (
 /* makeMessageFromCurrentFileCommentedDirective */
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#MAKEMESSAGEFROMCURRENTFILECOMMENTEDDIRECTIVE
- * @param {CommentedDirective} commentedDirective $COMMENT#JSDOC#PARAMS#DIRECTIVE21#COMMENTEDDIRECTIVE
- * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#MAKEMESSAGEFROMCURRENTFILECOMMENTEDDIRECTIVE
+ * Lists in an message the commented modules incompatible with a commented module based on its commented directive.
+ * @param {CommentedDirective} commentedDirective The commented directive of the commented module.
+ * @returns The message listing the incompatible commented modules.
  */
 export const makeMessageFromCurrentFileCommentedDirective = (
   commentedDirective,
@@ -385,10 +385,10 @@ export const makeMessageFromCurrentFileCommentedDirective = (
 /* findSpecificViolationMessage */
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#FINDSPECIFICVIOLATIONMESSAGE
- * @param {CommentedDirective} currentFileCommentedDirective $COMMENT#JSDOC#PARAMS#DIRECTIVE21#CURRENTFILECOMMENTEDDIRECTIVE
- * @param {CommentedDirective} importedFileCommentedDirective $COMMENT#JSDOC#PARAMS#DIRECTIVE21#IMPORTEDFILECOMMENTEDDIRECTIVE
- * @returns $COMMENT#JSDOC#RETURNS#FINDSPECIFICVIOLATIONMESSAGE
+ * Finds the `message` for the specific violation of commented directives import rules based on `commentedDirectives_BlockedImports`.
+ * @param {CommentedDirective} currentFileCommentedDirective The current file's commented directive.
+ * @param {CommentedDirective} importedFileCommentedDirective The imported file's commented directive.
+ * @returns The corresponding `message`.
  */
 export const findSpecificViolationMessage = (
   currentFileCommentedDirective,

package/library/directive21/config.js

@@ -12,9 +12,9 @@ import {
  */
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#DIRECTIVE21#MAKEDIRECTIVE21CONFIG
- * @param {Plugin} plugin $COMMENT#JSDOC#PARAMS#PLUGIN
- * @returns $COMMENT#JSDOC#RETURNS#DIRECTIVE21#MAKEDIRECTIVE21CONFIG
+ * 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.
  */
 export const makeDirective21Config = (plugin) => ({
   [directive21ConfigName]: defineConfig([

package/library/index.js

@@ -165,10 +165,10 @@ export {
 export { directive21Data } from "../jscomments/_commons/constants/data.js";
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#DEFINEDIRECTIVE21
+ * Creates the ESLint config object required as the basis for the Directive-First Architecture, linting server-client-agnostic imports based on their commented directives. (Defaults to `"warn"`. You can import and use ```[`${useAgnosticPluginName}/${directive21ConfigName}`]``` later in a further ESLint config object to modify that value.)
  * @template {string} T
- * @param {T} reactFolder $COMMENT#JSDOC#PARAMS#REACTFOLDER
- * @returns $COMMENT#JSDOC#RETURNS#DEFINEDIRECTIVE21
+ * @param {T} reactFolder The path of the project's React folder where everything React lives, relative to the root of the project. This is, for example, the app directory when using the Next.js App Router, as `"app"`.
+ * @returns An ESLint config object that applies `eslint-plugin-use-agnostic`'s `directive21` config by using the provided `reactFolder` as the basis for JavaScript/TypeScript glob patterns.
  */
 export const defineDirective21 = (reactFolder) => {
   /** @type {[`${T}/*\*\/*.tsx`, `${T}/*\*\/*.ts`, `${T}/*\*\/*.jsx`, `${T}/*\*\/*.js`, `${T}/*\*\/*.mjs`, `${T}/*\*\/*.cjs`]} */
@@ -195,13 +195,13 @@ export const defineDirective21 = (reactFolder) => {
 };
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#DEFINECONFIGSETTINGS
+ * Defines the config settings for the eXtra JSX VS Code extension as a means to configure `eXtra JSX` directly from ESLint, given the fact that `eslint-plugin-use-agnostic` and `eXtra JSX` have to work together in making the Directive-First Architecture.
  * @template {string} T
  * @template {string} U
- * @param {Object} settings $COMMENT#JSDOC#PARAMS#SETTINGS
- * @param {T} settings.reactFolder $COMMENT#JSDOC#PARAMS#REACTFOLDER
- * @param {U} settings.rootPath $COMMENT#JSDOC#PARAMS#ROOTPATH
- * @returns $COMMENT#JSDOC#RETURNS#DEFINECONFIGSETTINGS
+ * @param {Object} settings The settings as follows:
+ * @param {T} settings.reactFolder The path of the project's React folder where everything React lives, relative to the root of the project. This is, for example, the app directory when using the Next.js App Router, as `"app"`.
+ * @param {U} settings.rootPath The absolute path of the root of the project, from which the absolute path of the React folder can be easily obtained.
+ * @returns The config object responsible for the settings retrieved by the eXtra JSX VS Code extension.
  */
 export const defineConfigSettings = ({ reactFolder, rootPath }) => {
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-use-agnostic",
-  "version": "2.0.8",
+  "version": "2.1.0",
   "description": "Highlights problematic server-client imports in projects made with the Fullstack React Architecture.",
   "keywords": [
     "eslint",