eslint-plugin-use-agnostic 2.0.8 → 2.1.0

package/library/directive21/_commons/constants/bases.js

@@ -141,7 +141,7 @@ export const AT_SERVER_FUNCTIONS =
 export const AT_CLIENT_CONTEXTS =
   commentVariablesData.directive21["use client contexts"].atStrategy.value;
 // export const AT_AGNOSTIC_CONDITIONS =
-//   commentVariablesData.directive21["use agnostic conditions"].atStrategy.value; // $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#KINDSSIMPLE Modules no longer output from Agnostic Strategies Modules.
+//   commentVariablesData.directive21["use agnostic conditions"].atStrategy.value; // Agnostic Conditions Modules no longer output from Agnostic Strategies Modules.
 
 // commented strategies array
 /** @type {CommentedStrategies} */
@@ -209,12 +209,12 @@ export const commentedDirectives_verificationReports = Object.freeze({
 /* commentedDirectives_blockedImports */
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#AGNOSTIC20#MAKEBLOCKEDIMPORT
+ * Makes a blockedImport object for the identified blocked import at hand.
  * @template {CommentedDirective} T
  * @template {CommentedDirective} U
- * @param {T} currentFileCommentedDirective $COMMENT#JSDOC#PARAMS#DIRECTIVE21#CURRENTFILECOMMENTEDDIRECTIVE
- * @param {U} importedFileCommentedDirective $COMMENT#JSDOC#PARAMS#DIRECTIVE21#IMPORTEDFILECOMMENTEDDIRECTIVE
- * @returns $COMMENT#JSDOC#RETURNS#AGNOSTIC20#MAKEBLOCKEDIMPORT
+ * @param {T} currentFileCommentedDirective The current file's commented directive.
+ * @param {U} importedFileCommentedDirective The imported file's commented directive.
+ * @returns The blockedImport object for the identified blocked import at hand.
  */
 export const makeBlockedImport = (
   currentFileCommentedDirective,
@@ -235,244 +235,244 @@ export const makeBlockedImport = (
 
 export const commentedDirectives_blockedImports = Object.freeze({
   [USE_SERVER_LOGICS]: Object.freeze([
-    // USE_SERVER_LOGICS $COMMENT#DIRECTIVE21#USE_SERVER_LOGICS#USE_SERVER_LOGICS
+    // USE_SERVER_LOGICS Prime Server Logics can compose with one another.
     makeBlockedImport(
       USE_SERVER_LOGICS,
       USE_CLIENT_LOGICS,
-    ) /* $COMMENT#DIRECTIVE21#FORALIASVARIABLES#CLIENTNEVERSERVER */,
-    // USE_AGNOSTIC_LOGICS $COMMENT#DIRECTIVE21#FORALIASVARIABLES#AGNOSTICCANSERVERCLIENT
-    // USE_SERVER_COMPONENTS $COMMENT#DIRECTIVE21#USE_SERVER_LOGICS#USE_SERVER_COMPONENTS
+    ) /* Prime Client Logics should never leak to the server. */,
+    // USE_AGNOSTIC_LOGICS Prime Agnostic Logics can run safely on the server just like they can on the client.
+    // USE_SERVER_COMPONENTS Lineal Server Components are OK to be composed with Prime Server Logics as long as the Prime Server Logics Module, by convention, does not export React components.
     makeBlockedImport(
       USE_SERVER_LOGICS,
       USE_CLIENT_COMPONENTS,
-    ) /* $COMMENT#DIRECTIVE21#USE_SERVER_LOGICS#USE_CLIENT_COMPONENTS */,
-    // USE_AGNOSTIC_COMPONENTS $COMMENT#DIRECTIVE21#FORALIASVARIABLES#AGNOSTICCOMPONENTSCANANY
-    // USE_SERVER_FUNCTIONS $COMMENT#DIRECTIVE21#USE_SERVER_LOGICS#USE_SERVER_FUNCTIONS
+    ) /* Lineal Client Components, like any Client Components, cannot be tinkered with on the server. */,
+    // USE_AGNOSTIC_COMPONENTS Lineal Agnostic Components can be composed with any Prime Environment Logics agnostically, as long as the Prime Environment Logics Module, by convention, does not export React components.
+    // USE_SERVER_FUNCTIONS (Special) Server Functions, being able to import one another, can compose and do so via Prime Server Logics, despite this method seeming superfluous at first glance. (Perhaps a preferrable use case for this has been found or could be found either today or in the future.)
     makeBlockedImport(
       USE_SERVER_LOGICS,
       USE_CLIENT_CONTEXTS,
-    ) /* $COMMENT#DIRECTIVE21#USE_SERVER_LOGICS#USE_CLIENT_CONTEXTS */,
-    // USE_AGNOSTIC_CONDITIONS $COMMENT#DIRECTIVE21#USE_SERVER_COMPONENTS#USE_AGNOSTIC_CONDITIONS
+    ) /* (Special) Client Contexts Components, like any Client Components, cannot be tinkered with on the server. */,
+    // USE_AGNOSTIC_CONDITIONS (Special) Agnostic Conditions Components and/or Logics, as if they were Lineal Agnostic Components and/or Prime Agnostic Logics themselves, can render safely on the server just like they can on the client.
     makeBlockedImport(
       USE_SERVER_LOGICS,
       USE_AGNOSTIC_STRATEGIES,
-    ) /* $COMMENT#DIRECTIVE21#USE_AGNOSTIC_STRATEGIES#INVALID */,
+    ) /* (Special) Agnostic Strategies Modules cannot be imported by any of the known modules, since given that Agnostic Strategies Modules generate strategized files, they need to be imported via their strategized files (like those ending in `.serverLogics.ts`) instead. */,
   ]),
   [USE_CLIENT_LOGICS]: Object.freeze([
     makeBlockedImport(
       USE_CLIENT_LOGICS,
       USE_SERVER_LOGICS,
-    ) /* $COMMENT#DIRECTIVE21#FORALIASVARIABLES#SERVERNEVERCLIENT */,
-    // USE_CLIENT_LOGICS $COMMENT#DIRECTIVE21#USE_CLIENT_LOGICS#USE_CLIENT_LOGICS
-    // USE_AGNOSTIC_LOGICS $COMMENT#DIRECTIVE21#FORALIASVARIABLES#AGNOSTICCANCLIENTSERVER
+    ) /* Prime Server Logics should never leak to the client. */,
+    // USE_CLIENT_LOGICS Prime Client Logics can compose with one another.
+    // USE_AGNOSTIC_LOGICS Prime Agnostic Logics can run safely on the client just like they can on the server.
     makeBlockedImport(
       USE_CLIENT_LOGICS,
       USE_SERVER_COMPONENTS,
-    ) /* $COMMENT#DIRECTIVE21#USE_CLIENT_LOGICS#USE_SERVER_COMPONENTS */,
-    // USE_CLIENT_COMPONENTS $COMMENT#DIRECTIVE21#USE_CLIENT_LOGICS#USE_CLIENT_COMPONENTS
-    // USE_AGNOSTIC_COMPONENTS $COMMENT#DIRECTIVE21#FORALIASVARIABLES#AGNOSTICCOMPONENTSCANANY
-    // USE_SERVER_FUNCTIONS $COMMENT#DIRECTIVE21#USE_CLIENT_LOGICS#USE_SERVER_FUNCTIONS
-    // USE_CLIENT_CONTEXTS $COMMENT#DIRECTIVE21#USE_CLIENT_LOGICS#USE_CLIENT_CONTEXTS
-    // USE_AGNOSTIC_CONDITIONS $COMMENT#DIRECTIVE21#USE_CLIENT_COMPONENTS#USE_AGNOSTIC_CONDITIONS
+    ) /* Lineal Server Components cannot be tinkered with on the client. */,
+    // USE_CLIENT_COMPONENTS Lineal Client Components, like any Client Components, are OK to be composed with Prime Client Logics as long as the Prime Client Logics Module, by convention, does not export React components.
+    // USE_AGNOSTIC_COMPONENTS Lineal Agnostic Components can be composed with any Prime Environment Logics agnostically, as long as the Prime Environment Logics Module, by convention, does not export React components.
+    // USE_SERVER_FUNCTIONS (Special) Server Functions can technically be attached to any Client Components being tinkered with within Client Logics Modules.
+    // USE_CLIENT_CONTEXTS (Special) Client Contexts Components, like any Client Components, are OK to be composed with Prime Client Logics as long as the Prime Client Logics Module, by convention, does not export React components.
+    // USE_AGNOSTIC_CONDITIONS (Special) Agnostic Conditions Components and/or Logics, as if they were Lineal Agnostic Components and/or Prime Agnostic Logics themselves, can render safely on the client just like they can on the server.
     makeBlockedImport(
       USE_CLIENT_LOGICS,
       USE_AGNOSTIC_STRATEGIES,
-    ) /* $COMMENT#DIRECTIVE21#USE_AGNOSTIC_STRATEGIES#INVALID */,
+    ) /* (Special) Agnostic Strategies Modules cannot be imported by any of the known modules, since given that Agnostic Strategies Modules generate strategized files, they need to be imported via their strategized files (like those ending in `.serverLogics.ts`) instead. */,
   ]),
   [USE_AGNOSTIC_LOGICS]: Object.freeze([
     makeBlockedImport(
       USE_AGNOSTIC_LOGICS,
       USE_SERVER_LOGICS,
-    ) /* $COMMENT#DIRECTIVE21#FORALIASVARIABLES#SERVERLOGICSCANTBOTH */,
+    ) /* Prime Server Logics cannot run on both the server and the client. */,
     makeBlockedImport(
       USE_AGNOSTIC_LOGICS,
       USE_CLIENT_LOGICS,
-    ) /* $COMMENT#DIRECTIVE21#FORALIASVARIABLES#CLIENTLOGICSCANTBOTH */,
-    // USE_AGNOSTIC_LOGICS $COMMENT#DIRECTIVE21#USE_AGNOSTIC_LOGICS#USE_AGNOSTIC_LOGICS
+    ) /* Prime Client Logics cannot run on both the server and the client. */,
+    // USE_AGNOSTIC_LOGICS Prime Agnostic Logics can compose with one another.
     makeBlockedImport(
       USE_AGNOSTIC_LOGICS,
       USE_SERVER_COMPONENTS,
-    ) /* $COMMENT#DIRECTIVE21#USE_AGNOSTIC_LOGICS#USE_SERVER_COMPONENTS */,
+    ) /* Lineal Server Components cannot be tinkered with on both the server and the client. */,
     makeBlockedImport(
       USE_AGNOSTIC_LOGICS,
       USE_CLIENT_COMPONENTS,
-    ) /* $COMMENT#DIRECTIVE21#USE_AGNOSTIC_LOGICS#USE_CLIENT_COMPONENTS */,
-    // USE_AGNOSTIC_COMPONENTS $COMMENT#DIRECTIVE21#FORALIASVARIABLES#AGNOSTICCOMPONENTSCANANY
+    ) /* Lineal Client Components, like any Client Components, cannot be tinkered with on both the server and the client. */,
+    // USE_AGNOSTIC_COMPONENTS Lineal Agnostic Components can be composed with any Prime Environment Logics agnostically, as long as the Prime Environment Logics Module, by convention, does not export React components.
     makeBlockedImport(
       USE_AGNOSTIC_LOGICS,
       USE_SERVER_FUNCTIONS,
-    ) /* $COMMENT#DIRECTIVE21#USE_AGNOSTIC_LOGICS#USE_SERVER_FUNCTIONS */,
+    ) /* (Special) Server Functions can be modified on the server and on the client, but their use cases on both environments are not one-to-one compatible, since they're being addressed as they are on the server and addressed as references on the client. */,
     makeBlockedImport(
       USE_AGNOSTIC_LOGICS,
       USE_CLIENT_CONTEXTS,
-    ) /* $COMMENT#DIRECTIVE21#USE_AGNOSTIC_LOGICS#USE_CLIENT_CONTEXTS */,
+    ) /* (Special) Client Contexts Components, like any Client Components, cannot be tinkered with on both the server and the client. */,
     makeBlockedImport(
       USE_AGNOSTIC_LOGICS,
       USE_AGNOSTIC_CONDITIONS,
-    ) /* $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#INVALIDENVIRONMENT */,
+    ) /* (Special) Agnostic Conditions Modules cannot be imported in the (Abstract) Agnostic Environment, only strictly on the server or strictly on the client. */,
     makeBlockedImport(
       USE_AGNOSTIC_LOGICS,
       USE_AGNOSTIC_STRATEGIES,
-    ) /* $COMMENT#DIRECTIVE21#USE_AGNOSTIC_STRATEGIES#INVALID */,
+    ) /* (Special) Agnostic Strategies Modules cannot be imported by any of the known modules, since given that Agnostic Strategies Modules generate strategized files, they need to be imported via their strategized files (like those ending in `.serverLogics.ts`) instead. */,
   ]),
   [USE_SERVER_COMPONENTS]: Object.freeze([
-    // USE_SERVER_LOGICS $COMMENT#DIRECTIVE21#USE_SERVER_COMPONENTS#USE_SERVER_LOGICS
+    // USE_SERVER_LOGICS Prime Server Logics, being logic from the server, can safely support Lineal Server Components.
     makeBlockedImport(
       USE_SERVER_COMPONENTS,
       USE_CLIENT_LOGICS,
-    ) /* $COMMENT#DIRECTIVE21#FORALIASVARIABLES#CLIENTNEVERSERVER */,
-    // USE_AGNOSTIC_LOGICS $COMMENT#DIRECTIVE21#FORALIASVARIABLES#AGNOSTICCANSERVERCLIENT
-    // USE_SERVER_COMPONENTS $COMMENT#DIRECTIVE21#USE_SERVER_COMPONENTS#USE_SERVER_COMPONENTS
-    // USE_CLIENT_COMPONENTS $COMMENT#DIRECTIVE21#USE_SERVER_COMPONENTS#USE_CLIENT_COMPONENTS
-    // USE_AGNOSTIC_COMPONENTS $COMMENT#DIRECTIVE21#USE_SERVER_COMPONENTS#USE_AGNOSTIC_COMPONENTS
-    // USE_SERVER_FUNCTIONS $COMMENT#DIRECTIVE21#USE_SERVER_COMPONENTS#USE_SERVER_FUNCTIONS
-    // USE_CLIENT_CONTEXTS $COMMENT#DIRECTIVE21#USE_SERVER_COMPONENTS#USE_CLIENT_CONTEXTS
-    // USE_AGNOSTIC_CONDITIONS $COMMENT#DIRECTIVE21#USE_SERVER_COMPONENTS#USE_AGNOSTIC_CONDITIONS
+    ) /* Prime Client Logics should never leak to the server. */,
+    // USE_AGNOSTIC_LOGICS Prime Agnostic Logics can run safely on the server just like they can on the client.
+    // USE_SERVER_COMPONENTS Lineal Server Components can compose with one another, now that thanks to the inclusion of Agnostic Components they are actual Server Components.
+    // USE_CLIENT_COMPONENTS Lineal Client Components can be nested inside Lineal Server Components to create client boundaries when the root of the application is planted on the server.
+    // USE_AGNOSTIC_COMPONENTS Lineal Agnostic Components can render safely on the server just like they can on the client.
+    // USE_SERVER_FUNCTIONS (Special) Server Functions can be passed to imported Client Components within Lineal Server Components Modules, even though indeed Lineal Server Components Modules and Lineal Server Components can make their own Server Functions through inline `'use server'` directives.
+    // USE_CLIENT_CONTEXTS (Special) Client Contexts Components can be nested inside Lineal Server Components to wrap some of the tree with client state accessible through child Client Components, and to pass through Server Components when the root of the application is planted on the server.
+    // USE_AGNOSTIC_CONDITIONS (Special) Agnostic Conditions Components and/or Logics, as if they were Lineal Agnostic Components and/or Prime Agnostic Logics themselves, can render safely on the server just like they can on the client.
     makeBlockedImport(
       USE_SERVER_COMPONENTS,
       USE_AGNOSTIC_STRATEGIES,
-    ) /* $COMMENT#DIRECTIVE21#USE_AGNOSTIC_STRATEGIES#INVALID */,
+    ) /* (Special) Agnostic Strategies Modules cannot be imported by any of the known modules, since given that Agnostic Strategies Modules generate strategized files, they need to be imported via their strategized files (like those ending in `.serverLogics.ts`) instead. */,
   ]),
   [USE_CLIENT_COMPONENTS]: Object.freeze([
     makeBlockedImport(
       USE_CLIENT_COMPONENTS,
       USE_SERVER_LOGICS,
-    ) /* $COMMENT#DIRECTIVE21#FORALIASVARIABLES#SERVERNEVERCLIENT */,
-    // USE_CLIENT_LOGICS $COMMENT#DIRECTIVE21#USE_CLIENT_COMPONENTS#USE_CLIENT_LOGICS
-    // USE_AGNOSTIC_LOGICS $COMMENT#DIRECTIVE21#FORALIASVARIABLES#AGNOSTICCANCLIENTSERVER
+    ) /* Prime Server Logics should never leak to the client. */,
+    // USE_CLIENT_LOGICS Prime Client Logics, being logic from the client, can safely support Lineal Client Components, like any Client Components.
+    // USE_AGNOSTIC_LOGICS Prime Agnostic Logics can run safely on the client just like they can on the server.
     makeBlockedImport(
       USE_CLIENT_COMPONENTS,
       USE_SERVER_COMPONENTS,
-    ) /* $COMMENT#DIRECTIVE21#USE_CLIENT_COMPONENTS#USE_SERVER_COMPONENTS */,
-    // USE_CLIENT_COMPONENTS $COMMENT#DIRECTIVE21#USE_CLIENT_COMPONENTS#USE_CLIENT_COMPONENTS
-    // USE_AGNOSTIC_COMPONENTS $COMMENT#DIRECTIVE21#FORALIASVARIABLES#AGNOSTICCOMPONENTSRENDERANY
-    // USE_SERVER_FUNCTIONS $COMMENT#DIRECTIVE21#FORALIASVARIABLES#SERVERFUNCTIONSCLIENT
-    // USE_CLIENT_CONTEXTS $COMMENT#DIRECTIVE21#USE_CLIENT_COMPONENTS#USE_CLIENT_CONTEXTS
-    // USE_AGNOSTIC_CONDITIONS $COMMENT#DIRECTIVE21#USE_CLIENT_COMPONENTS#USE_AGNOSTIC_CONDITIONS
+    ) /* Lineal Server Components cannot be the children of Lineal Client Components. */,
+    // USE_CLIENT_COMPONENTS Lineal Client Components can compose with one another.
+    // USE_AGNOSTIC_COMPONENTS Lineal Agnostic Components can render safely on the client just like they can on the server.
+    // USE_SERVER_FUNCTIONS (Special) Server Functions can be specifically triggered by Client Components.
+    // USE_CLIENT_CONTEXTS (Special) Client Contexts Components can effectively become Lineal and only render their children on the client via this mechanism since, by a Client Contexts Component being the child of a Lineal Client Component, the Client Contexts Component's children become the grandchildren of an ancestor Lineal Client Component, enforcing them to render exclusively on the client.
+    // USE_AGNOSTIC_CONDITIONS (Special) Agnostic Conditions Components and/or Logics, as if they were Lineal Agnostic Components and/or Prime Agnostic Logics themselves, can render safely on the client just like they can on the server.
     makeBlockedImport(
       USE_CLIENT_COMPONENTS,
       USE_AGNOSTIC_STRATEGIES,
-    ) /* $COMMENT#DIRECTIVE21#USE_AGNOSTIC_STRATEGIES#INVALID */,
+    ) /* (Special) Agnostic Strategies Modules cannot be imported by any of the known modules, since given that Agnostic Strategies Modules generate strategized files, they need to be imported via their strategized files (like those ending in `.serverLogics.ts`) instead. */,
   ]),
   [USE_AGNOSTIC_COMPONENTS]: Object.freeze([
     makeBlockedImport(
       USE_AGNOSTIC_COMPONENTS,
       USE_SERVER_LOGICS,
-    ) /* $COMMENT#DIRECTIVE21#FORALIASVARIABLES#SERVERLOGICSCANTBOTH */,
+    ) /* Prime Server Logics cannot run on both the server and the client. */,
     makeBlockedImport(
       USE_AGNOSTIC_COMPONENTS,
       USE_CLIENT_LOGICS,
-    ) /* $COMMENT#DIRECTIVE21#FORALIASVARIABLES#CLIENTLOGICSCANTBOTH */,
-    // USE_AGNOSTIC_LOGICS $COMMENT#DIRECTIVE21#USE_AGNOSTIC_COMPONENTS#USE_AGNOSTIC_LOGICS
+    ) /* Prime Client Logics cannot run on both the server and the client. */,
+    // USE_AGNOSTIC_LOGICS Prime Agnostic Logics, being environment-agnostic logic, can safely support any Agnostic Components.
     makeBlockedImport(
       USE_AGNOSTIC_COMPONENTS,
       USE_SERVER_COMPONENTS,
-    ) /* $COMMENT#DIRECTIVE21#USE_AGNOSTIC_COMPONENTS#USE_SERVER_COMPONENTS */,
-    // USE_CLIENT_COMPONENTS $COMMENT#DIRECTIVE21#USE_AGNOSTIC_COMPONENTS#USE_CLIENT_COMPONENTS
-    // USE_AGNOSTIC_COMPONENTS $COMMENT#DIRECTIVE21#USE_AGNOSTIC_COMPONENTS#USE_AGNOSTIC_COMPONENTS
-    // USE_SERVER_FUNCTIONS $COMMENT#DIRECTIVE21#USE_AGNOSTIC_COMPONENTS#USE_SERVER_FUNCTIONS
-    // USE_CLIENT_CONTEXTS $COMMENT#DIRECTIVE21#USE_AGNOSTIC_COMPONENTS#USE_CLIENT_CONTEXTS
+    ) /* Lineal Server Components, unlike Lineal Client Components, cannot make silos of their own once on the opposing environment (the client in this case), and therefore cannot be executed from the client, making them unable to execute agnostically from both the server and the client. */,
+    // USE_CLIENT_COMPONENTS Lineal Client Components can be nested inside Lineal Agnostic Components to create client boundaries when the root of the application is planted on the server.
+    // USE_AGNOSTIC_COMPONENTS Lineal Agnostic Components can compose with one another.
+    // USE_SERVER_FUNCTIONS (Special) Server Functions can be passed to Client Components as props when Client Components are also legally imported into Agnostic Components Modules.
+    // USE_CLIENT_CONTEXTS (Special) Client Contexts Components can be nested inside Lineal Agnostic Components to wrap some of the tree with client state accessible through child Client Components, and to pass through Server Components — if still on the Server Tree — when the root of the application is planted on the server.
     makeBlockedImport(
       USE_AGNOSTIC_COMPONENTS,
       USE_AGNOSTIC_CONDITIONS,
-    ) /* $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#INVALIDENVIRONMENT */,
+    ) /* (Special) Agnostic Conditions Modules cannot be imported in the (Abstract) Agnostic Environment, only strictly on the server or strictly on the client. */,
     makeBlockedImport(
       USE_AGNOSTIC_COMPONENTS,
       USE_AGNOSTIC_STRATEGIES,
-    ) /* $COMMENT#DIRECTIVE21#USE_AGNOSTIC_STRATEGIES#INVALID */,
+    ) /* (Special) Agnostic Strategies Modules cannot be imported by any of the known modules, since given that Agnostic Strategies Modules generate strategized files, they need to be imported via their strategized files (like those ending in `.serverLogics.ts`) instead. */,
   ]),
   [USE_SERVER_FUNCTIONS]: Object.freeze([
-    // USE_SERVER_LOGICS $COMMENT#DIRECTIVE21#USE_SERVER_FUNCTIONS#USE_SERVER_LOGICS
+    // USE_SERVER_LOGICS Prime Server Logics, being logic from the server, can safely support (Special) Server Functions.
     makeBlockedImport(
       USE_SERVER_FUNCTIONS,
       USE_CLIENT_LOGICS,
-    ) /* $COMMENT#DIRECTIVE21#FORALIASVARIABLES#CLIENTNEVERSERVER */,
-    // USE_AGNOSTIC_LOGICS $COMMENT#DIRECTIVE21#FORALIASVARIABLES#AGNOSTICCANSERVERCLIENT
+    ) /* Prime Client Logics should never leak to the server. */,
+    // USE_AGNOSTIC_LOGICS Prime Agnostic Logics can run safely on the server just like they can on the client.
     makeBlockedImport(
       USE_SERVER_FUNCTIONS,
       USE_SERVER_COMPONENTS,
-    ) /* $COMMENT#DIRECTIVE21#USE_SERVER_FUNCTIONS#USE_SERVER_COMPONENTS */,
+    ) /* Lineal Server Components aren't allowed because (Special) Server Functions have no business working with React Components. */,
     makeBlockedImport(
       USE_SERVER_FUNCTIONS,
       USE_CLIENT_COMPONENTS,
-    ) /* $COMMENT#DIRECTIVE21#USE_SERVER_FUNCTIONS#USE_CLIENT_COMPONENTS */,
+    ) /* Lineal Client Components aren't allowed because (Special) Server Functions have no business working with React Components. */,
     makeBlockedImport(
       USE_SERVER_FUNCTIONS,
       USE_AGNOSTIC_COMPONENTS,
-    ) /* $COMMENT#DIRECTIVE21#USE_SERVER_FUNCTIONS#USE_AGNOSTIC_COMPONENTS */,
-    // USE_SERVER_FUNCTIONS $COMMENT#DIRECTIVE21#USE_SERVER_FUNCTIONS#USE_SERVER_FUNCTIONS
+    ) /* Lineal Agnostic Components aren't allowed because (Special) Server Functions have no business working with React Components. */,
+    // USE_SERVER_FUNCTIONS (Special) Server Functions, even though they don't need to import one another and the same results can be generated via Prime Server Logics for the outcome of a single Server Function, can still compose with one another. (Perhaps a preferrable use case for this has been found or could be found either today or in the future.)
     makeBlockedImport(
       USE_SERVER_FUNCTIONS,
       USE_CLIENT_CONTEXTS,
-    ) /* $COMMENT#DIRECTIVE21#USE_SERVER_FUNCTIONS#USE_CLIENT_CONTEXTS */,
+    ) /* (Special) Client Contexts Components aren't allowed because (Special) Server Functions have no business working with React Components. */,
     makeBlockedImport(
       USE_SERVER_FUNCTIONS,
       USE_AGNOSTIC_CONDITIONS,
-    ) /* $COMMENT#DIRECTIVE21#USE_SERVER_FUNCTIONS#USE_AGNOSTIC_CONDITIONS */,
+    ) /* (Special) Agnostic Conditions Components and/or Logics aren't allowed because (Special) Server Functions have no business working with React Components. */,
     makeBlockedImport(
       USE_SERVER_FUNCTIONS,
       USE_AGNOSTIC_STRATEGIES,
-    ) /* $COMMENT#DIRECTIVE21#USE_AGNOSTIC_STRATEGIES#INVALID */,
+    ) /* (Special) Agnostic Strategies Modules cannot be imported by any of the known modules, since given that Agnostic Strategies Modules generate strategized files, they need to be imported via their strategized files (like those ending in `.serverLogics.ts`) instead. */,
   ]),
   [USE_CLIENT_CONTEXTS]: Object.freeze([
     makeBlockedImport(
       USE_CLIENT_CONTEXTS,
       USE_SERVER_LOGICS,
-    ) /* $COMMENT#DIRECTIVE21#FORALIASVARIABLES#SERVERNEVERCLIENT */,
-    // USE_CLIENT_LOGICS $COMMENT#DIRECTIVE21#USE_CLIENT_CONTEXTS#USE_CLIENT_LOGICS
-    // USE_AGNOSTIC_LOGICS $COMMENT#DIRECTIVE21#FORALIASVARIABLES#AGNOSTICCANCLIENTSERVER
+    ) /* Prime Server Logics should never leak to the client. */,
+    // USE_CLIENT_LOGICS Prime Client Logics, being logic from the client, can safely support (Special) Client Contexts Components, like any Client Components.
+    // USE_AGNOSTIC_LOGICS Prime Agnostic Logics can run safely on the client just like they can on the server.
     makeBlockedImport(
       USE_CLIENT_CONTEXTS,
       USE_SERVER_COMPONENTS,
-    ) /* $COMMENT#DIRECTIVE21#USE_CLIENT_CONTEXTS#USE_SERVER_COMPONENTS */,
-    // USE_CLIENT_COMPONENTS $COMMENT#DIRECTIVE21#USE_CLIENT_CONTEXTS#USE_CLIENT_COMPONENTS
-    // USE_AGNOSTIC_COMPONENTS $COMMENT#DIRECTIVE21#FORALIASVARIABLES#AGNOSTICCOMPONENTSRENDERANY
-    // USE_SERVER_FUNCTIONS $COMMENT#DIRECTIVE21#FORALIASVARIABLES#SERVERFUNCTIONSCLIENT
-    // USE_CLIENT_CONTEXTS $COMMENT#DIRECTIVE21#USE_CLIENT_CONTEXTS#USE_CLIENT_CONTEXTS
-    // USE_AGNOSTIC_CONDITIONS $COMMENT#DIRECTIVE21#USE_CLIENT_COMPONENTS#USE_AGNOSTIC_CONDITIONS
+    ) /* Lineal Server Components may only pass through (Special) Client Contexts Components via the children prop within Server Components Modules. */,
+    // USE_CLIENT_COMPONENTS Lineal Client Components can create client boundaries within (Special) Client Contexts Components.
+    // USE_AGNOSTIC_COMPONENTS Lineal Agnostic Components can render safely on the client just like they can on the server.
+    // USE_SERVER_FUNCTIONS (Special) Server Functions can be specifically triggered by Client Components.
+    // USE_CLIENT_CONTEXTS (Special) Client Contexts Components can compose with one another.
+    // USE_AGNOSTIC_CONDITIONS (Special) Agnostic Conditions Components and/or Logics, as if they were Lineal Agnostic Components and/or Prime Agnostic Logics themselves, can render safely on the client just like they can on the server.
     makeBlockedImport(
       USE_CLIENT_CONTEXTS,
       USE_AGNOSTIC_STRATEGIES,
-    ) /* $COMMENT#DIRECTIVE21#USE_AGNOSTIC_STRATEGIES#INVALID */,
+    ) /* (Special) Agnostic Strategies Modules cannot be imported by any of the known modules, since given that Agnostic Strategies Modules generate strategized files, they need to be imported via their strategized files (like those ending in `.serverLogics.ts`) instead. */,
   ]),
   [USE_AGNOSTIC_CONDITIONS]: Object.freeze([
-    // USE_SERVER_LOGICS $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#USE_SERVER_LOGICS
-    // USE_CLIENT_LOGICS $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#USE_CLIENT_LOGICS
-    // USE_AGNOSTIC_LOGICS $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#USE_AGNOSTIC_LOGICS
-    // USE_SERVER_COMPONENTS $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#USE_SERVER_COMPONENTS
-    // USE_CLIENT_COMPONENTS $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#USE_CLIENT_COMPONENTS
-    // USE_AGNOSTIC_COMPONENTS $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#USE_AGNOSTIC_COMPONENTS
+    // USE_SERVER_LOGICS Prime Server Logics are to be paired as `LogicForServer` utilities with `LogicForClient` utilities to form (Special) Agnostic Conditions Logics. The `LogicForServer` is always the first assigned. The exported variable should be prefixed by `utilize-`, like `utilizeUtility`.
+    // USE_CLIENT_LOGICS Prime Client Logics are to be paired as `LogicForClient` utilities with `LogicForServer` utilities to form (Special) Agnostic Conditions Logics. The `LogicForClient` is always the last assigned. The exported variable should be prefixed by `utilize-`, like `utilizeUtility`.
+    // USE_AGNOSTIC_LOGICS Prime Agnostic Logics can take the place of `LogicForServer` and/or `LogicForClient` utilities to form (Special) Agnostic Conditions Logics. The exported variable should be prefixed by `utilize-`, like `utilizeUtility`.
+    // USE_SERVER_COMPONENTS Lineal Server Components are to be paired as `ComponentForServer` components with `ComponentForClient` components to form (Special) Agnostic Conditions Components. The `ComponentForServer` is always the first assigned. The exported variable should be in PascalCase, like `ReactComponent`.
+    // USE_CLIENT_COMPONENTS Lineal Client Components are to be paired as `ComponentForClient` components with `ComponentForServer` components to form (Special) Agnostic Conditions Components. The `ComponentForClient` is always the last assigned. The exported variable should be in PascalCase, like `ReactComponent`.
+    // USE_AGNOSTIC_COMPONENTS Lineal Agnostic Components can take the place of `ComponentForServer` and/or `ComponentForClient` components to form (Special) Agnostic Conditions Components. The exported variable should be in PascalCase, like `ReactComponent`.
     makeBlockedImport(
       USE_AGNOSTIC_CONDITIONS,
       USE_SERVER_FUNCTIONS,
-    ) /* $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#USE_SERVER_FUNCTIONS */,
-    // USE_CLIENT_CONTEXTS $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#USE_CLIENT_CONTEXTS
+    ) /* (Special) Server Functions aren't allowed because they do not have 1-to-1 behavioral equivalents for the client that would satisfy (Special) Agnostic Conditions Modules. */,
+    // USE_CLIENT_CONTEXTS (Special) Client Contexts Components can actually be used as `ComponentForClient` arguments for (Special) Agnostic Conditions Components notably as counterparts to similar passthrough components selected as `ComponentForServer` arguments.
     makeBlockedImport(
       USE_AGNOSTIC_CONDITIONS,
       USE_AGNOSTIC_CONDITIONS,
-    ) /* $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#INVALIDENVIRONMENT */,
+    ) /* (Special) Agnostic Conditions Modules cannot be imported in the (Abstract) Agnostic Environment, only strictly on the server or strictly on the client. */,
     makeBlockedImport(
       USE_AGNOSTIC_CONDITIONS,
       USE_AGNOSTIC_STRATEGIES,
-    ) /* $COMMENT#DIRECTIVE21#USE_AGNOSTIC_STRATEGIES#INVALID */,
+    ) /* (Special) Agnostic Strategies Modules cannot be imported by any of the known modules, since given that Agnostic Strategies Modules generate strategized files, they need to be imported via their strategized files (like those ending in `.serverLogics.ts`) instead. */,
   ]),
   [USE_AGNOSTIC_STRATEGIES]: Object.freeze([
-    // USE_SERVER_LOGICS $COMMENT#DIRECTIVE21#USE_SERVER_LOGICS#KINDS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#DIRECTIVE21#USE_AGNOSTIC_STRATEGIES#SPECIALS Modules can import all known modules except Special Agnostic Modules, meaning themselves as file generators that should not be imported directly and (Special) $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#KINDSSIMPLE Modules which cannot be imported in the (Abstract) Agnostic Environment.
-    // USE_CLIENT_LOGICS $COMMENT#DIRECTIVE21#USE_CLIENT_LOGICS#KINDS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#DIRECTIVE21#USE_AGNOSTIC_STRATEGIES#SPECIALS Modules can import all known modules except Special Agnostic Modules, meaning themselves as file generators that should not be imported directly and (Special) $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#KINDSSIMPLE Modules which cannot be imported in the (Abstract) Agnostic Environment.
-    // USE_AGNOSTIC_LOGICS $COMMENT#DIRECTIVE21#USE_AGNOSTIC_LOGICS#KINDS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#DIRECTIVE21#USE_AGNOSTIC_STRATEGIES#SPECIALS Modules can import all known modules except Special Agnostic Modules, meaning themselves as file generators that should not be imported directly and (Special) $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#KINDSSIMPLE Modules which cannot be imported in the (Abstract) Agnostic Environment.
-    // USE_SERVER_COMPONENTS $COMMENT#DIRECTIVE21#USE_SERVER_COMPONENTS#KINDS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#DIRECTIVE21#USE_AGNOSTIC_STRATEGIES#SPECIALS Modules can import all known modules except Special Agnostic Modules, meaning themselves as file generators that should not be imported directly and (Special) $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#KINDSSIMPLE Modules which cannot be imported in the (Abstract) Agnostic Environment.
-    // USE_CLIENT_COMPONENTS $COMMENT#DIRECTIVE21#USE_CLIENT_COMPONENTS#KINDS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#DIRECTIVE21#USE_AGNOSTIC_STRATEGIES#SPECIALS Modules can import all known modules except Special Agnostic Modules, meaning themselves as file generators that should not be imported directly and (Special) $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#KINDSSIMPLE Modules which cannot be imported in the (Abstract) Agnostic Environment.
-    // USE_AGNOSTIC_COMPONENTS $COMMENT#DIRECTIVE21#USE_AGNOSTIC_COMPONENTS#KINDS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#DIRECTIVE21#USE_AGNOSTIC_STRATEGIES#SPECIALS Modules can import all known modules except Special Agnostic Modules, meaning themselves as file generators that should not be imported directly and (Special) $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#KINDSSIMPLE Modules which cannot be imported in the (Abstract) Agnostic Environment.
-    // USE_SERVER_FUNCTIONS $COMMENT#DIRECTIVE21#USE_SERVER_FUNCTIONS#SPECIALS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#DIRECTIVE21#USE_AGNOSTIC_STRATEGIES#SPECIALS Modules can import all known modules except Special Agnostic Modules, meaning themselves as file generators that should not be imported directly and (Special) $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#KINDSSIMPLE Modules which cannot be imported in the (Abstract) Agnostic Environment.
-    // USE_CLIENT_CONTEXTS $COMMENT#DIRECTIVE21#USE_CLIENT_CONTEXTS#SPECIALS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#DIRECTIVE21#USE_AGNOSTIC_STRATEGIES#SPECIALS Modules can import all known modules except Special Agnostic Modules, meaning themselves as file generators that should not be imported directly and (Special) $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#KINDSSIMPLE Modules which cannot be imported in the (Abstract) Agnostic Environment.
+    // USE_SERVER_LOGICS Prime Server Logics allowed, because (Special) Agnostic Strategies Modules can import all known modules except Special Agnostic Modules, meaning themselves as file generators that should not be imported directly and (Special) Agnostic Conditions Modules which cannot be imported in the (Abstract) Agnostic Environment.
+    // USE_CLIENT_LOGICS Prime Client Logics allowed, because (Special) Agnostic Strategies Modules can import all known modules except Special Agnostic Modules, meaning themselves as file generators that should not be imported directly and (Special) Agnostic Conditions Modules which cannot be imported in the (Abstract) Agnostic Environment.
+    // USE_AGNOSTIC_LOGICS Prime Agnostic Logics allowed, because (Special) Agnostic Strategies Modules can import all known modules except Special Agnostic Modules, meaning themselves as file generators that should not be imported directly and (Special) Agnostic Conditions Modules which cannot be imported in the (Abstract) Agnostic Environment.
+    // USE_SERVER_COMPONENTS Lineal Server Components allowed, because (Special) Agnostic Strategies Modules can import all known modules except Special Agnostic Modules, meaning themselves as file generators that should not be imported directly and (Special) Agnostic Conditions Modules which cannot be imported in the (Abstract) Agnostic Environment.
+    // USE_CLIENT_COMPONENTS Lineal Client Components allowed, because (Special) Agnostic Strategies Modules can import all known modules except Special Agnostic Modules, meaning themselves as file generators that should not be imported directly and (Special) Agnostic Conditions Modules which cannot be imported in the (Abstract) Agnostic Environment.
+    // USE_AGNOSTIC_COMPONENTS Lineal Agnostic Components allowed, because (Special) Agnostic Strategies Modules can import all known modules except Special Agnostic Modules, meaning themselves as file generators that should not be imported directly and (Special) Agnostic Conditions Modules which cannot be imported in the (Abstract) Agnostic Environment.
+    // USE_SERVER_FUNCTIONS (Special) Server Functions allowed, because (Special) Agnostic Strategies Modules can import all known modules except Special Agnostic Modules, meaning themselves as file generators that should not be imported directly and (Special) Agnostic Conditions Modules which cannot be imported in the (Abstract) Agnostic Environment.
+    // USE_CLIENT_CONTEXTS (Special) Client Contexts Components allowed, because (Special) Agnostic Strategies Modules can import all known modules except Special Agnostic Modules, meaning themselves as file generators that should not be imported directly and (Special) Agnostic Conditions Modules which cannot be imported in the (Abstract) Agnostic Environment.
     makeBlockedImport(
       USE_AGNOSTIC_STRATEGIES,
       USE_AGNOSTIC_CONDITIONS,
-    ) /* $COMMENT#DIRECTIVE21#USE_AGNOSTIC_CONDITIONS#INVALIDENVIRONMENT */,
+    ) /* (Special) Agnostic Conditions Modules cannot be imported in the (Abstract) Agnostic Environment, only strictly on the server or strictly on the client. */,
     makeBlockedImport(
       USE_AGNOSTIC_STRATEGIES,
       USE_AGNOSTIC_STRATEGIES,
-    ) /* $COMMENT#DIRECTIVE21#USE_AGNOSTIC_STRATEGIES#INVALID */,
+    ) /* (Special) Agnostic Strategies Modules cannot be imported by any of the known modules, since given that Agnostic Strategies Modules generate strategized files, they need to be imported via their strategized files (like those ending in `.serverLogics.ts`) instead. */,
   ]),
 });
 

package/library/directive21/_commons/rules/import-rules.js

@@ -88,24 +88,19 @@ In this context, {{ ${specificFailure} }} `,
     const rootPath = /** @type {string | undefined} */ (
       context.settings.eXtraJSX?.rootPath
     );
-    console.debug("reactFolder is:", reactFolder);
-    console.debug("rootPath is:", rootPath);
 
     if (!reactFolder || !rootPath) return {};
-    // make the resolver by resolving the TypeScript from the rootPath (getTsConfigPaths, makeAbsoluteFromTsConfigPaths, makeResolverFromAbsoluteTsConfigPaths)
-    // pass the resolver to importsFlow, allExportsFlow, importsFlowRequire (resolver.resolveFileSync, getCommentedDirectiveFromModule)
+    // make the resolver by resolving TypeScript from the rootPath (getTsConfigPaths, makeAbsoluteFromTsConfigPaths, makeResolverFromAbsoluteTsConfigPaths) // DONE.
+    // pass the resolver to importsFlow, allExportsFlow, importsFlowRequire (resolver.resolveFileSync, getCommentedDirectiveFromModule) // DONE. getCommentedDirectiveFromModule CANCELLED.
 
     const tsConfigPaths = getTsConfigPaths(rootPath);
-    console.debug("tsConfigPaths is:", tsConfigPaths);
     const absoluteTsConfigPaths = makeAbsoluteFromTsConfigPaths(
       rootPath,
       tsConfigPaths,
     );
-    console.debug("absoluteTsConfigPaths is:", absoluteTsConfigPaths);
     const resolver = makeResolverFromAbsoluteTsConfigPaths(
       absoluteTsConfigPaths,
     );
-    console.debug("resolver is:", resolver);
 
     if (result.skip) return {};
     const { verifiedCommentedDirective } = result; // Leave untouched. Since this is the verifying process. Commented directives from imported modules however, don't need to be further verified, and can simply be obtained by the flat module index.
@@ -134,6 +129,11 @@ In this context, {{ ${specificFailure} }} `,
   },
 };
 
+/**
+ * (directly copied from Extra JavaScript, so trust me bro)
+ * @param {string} rootPath
+ * @returns
+ */
 const getTsConfigPaths = (rootPath) => {
   const tsConfigJsonPath = path.join(rootPath, "tsconfig.json");
   const parsed = ts.getParsedCommandLineOfConfigFile(
@@ -148,6 +148,12 @@ const getTsConfigPaths = (rootPath) => {
   return paths;
 };
 
+/**
+ * (directly copied from Extra JavaScript, so trust me bro)
+ * @param {string} rootPath
+ * @param {ts.MapLike<string[]>} tsConfigPaths
+ * @returns
+ */
 const makeAbsoluteFromTsConfigPaths = (rootPath, tsConfigPaths) => {
   /** @type {Record<string, string[]>} */
   const results = {};
@@ -161,6 +167,11 @@ const makeAbsoluteFromTsConfigPaths = (rootPath, tsConfigPaths) => {
   return results;
 };
 
+/**
+ * (directly copied from Extra JavaScript, so trust me bro)
+ * @param {Record<string, string[]>} absoluteTsConfigPaths
+ * @returns
+ */
 const makeResolverFromAbsoluteTsConfigPaths = (absoluteTsConfigPaths) =>
   new ResolverFactory({
     extensions: EXTENSIONS,

package/library/directive21/_commons/utilities/analyze-exports-re.js

@@ -11,9 +11,9 @@
 import { walkAST } from "../../../_commons/utilities/walk-ast.js";
 
 /**
- * $COMMENT#JSDOC#DEFINITIONS#ANALYZEEXPORTSFORREEXPORTS
- * @param {SourceCode} sourceCode $COMMENT#JSDOC#PARAMS#SOURCECODEB
- * @returns $COMMENT#JSDOC#RETURNS#ANALYZEEXPORTSFORREEXPORTS
+ * Analyzes a source code's exports to detect re-exports.
+ * @param {SourceCode} sourceCode The `SourceCode` to analyze.
+ * @returns An object with the `reExportsWithSource` key tracking the direct re-exports from an imported source in an array and the `reExportsViaLocal` key tracking the indirect re-exports from an imported source in an array.
  */
 export const analyzeExportsForReExports = (sourceCode) => {
   /** @type {Map<string, {source: string, importNode: ImportDeclaration}>} */