eslint-plugin-use-agnostic 1.6.7 → 1.6.9

package/README.md

@@ -104,4 +104,4 @@ But not having a directive to distinguish between 1. non-special Server Modules
 
 This is what the `'use agnostic'` directive solves. It clearly marks a module to be an Agnostic Module. And if a module that used to lack a directive can now be marked as an Agnostic Module, this allows modules without a directive to finally, truly be Server Modules by default. And `eslint-plugin-use-agnostic` can work from there.
 
-A lot more needs to be done, and I suspect a lot of it unfortunately can only be optimized deeperly into React's innerworkings. But if the introduction of `'use agnostic'` can already create such powerful static analysis, imagine what it could produce if only it were incorporated into React as an official directive of the Fullstack React Architecture.
+A lot more needs to be done, and I suspect a lot of it unfortunately can only be optimized more deeply into React's innerworkings. But if the introduction of `'use agnostic'` can already create such powerful static analysis, imagine what it could produce if only it were incorporated into React as an official directive of the Fullstack React Architecture.

package/library/_commons/constants/bases.js

@@ -43,13 +43,15 @@ export const useServerJSXMessageId = "use-server-has-jsx-extension";
 // directive21
 export const importBreaksCommentedImportRulesMessageId =
   "import-breaks-commented-directive-import-rule";
-export const noCommentedDirective = "no-commented-directive-detected";
-export const commentedDirectiveVerificationFailed =
+export const noCommentedDirectiveMessageId = "no-commented-directive-detected";
+export const commentedDirectiveVerificationFailedMessageId =
   "commented-directive-verification-failed";
-export const importNotStrategized =
+export const importNotStrategizedMessageId =
   "import-from-use-agnostic-strategies-not-strategized";
-export const exportNotStrategized =
+export const exportNotStrategizedMessageId =
   "export-from-use-agnostic-strategies-not-strategized";
+export const cantChainImportAcrossEnvironmentsMessageId =
+  "cant-chain-import-across-environments";
 
 // all "resolved" directives (from AIA/agnostic20 & DFA/directive21)
 // - AIA: Agnostic-Included Architecture (agnostic20)

package/library/_commons/utilities/helpers.js

@@ -17,9 +17,9 @@ import {
 /* highlightFirstLineOfCode */
 
 /**
- * Gets the coordinates for the first line of code of a file.
- * @param {Context} context An ESLint rule's `context` object.
- * @returns The `context.report` `loc`-compatible coordinates for the first line of code of a file.
+ * $COMMENT#JSDOC#DEFINITIONS#HIGHLIGHTFIRSTLINEOFCODE
+ * @param {Context} context $COMMENT#JSDOC#PARAMS#CONTEXTA
+ * @returns $COMMENT#JSDOC#RETURNS#HIGHLIGHTFIRSTLINEOFCODE
  */
 export const highlightFirstLineOfCode = (context) => ({
   start: { line: 1, column: 0 },
@@ -29,13 +29,13 @@ export const highlightFirstLineOfCode = (context) => ({
 /* isImportBlocked */
 
 /**
- * Returns a boolean deciding if an imported file's "resolved" directive is incompatible with the current file's "resolved" directive.
+ * $COMMENT#JSDOC#DEFINITIONS#ISIMPORTBLOCKED
  * @template {ResolvedDirectiveWithoutUseAgnosticStrategies} T
  * @template {ResolvedDirectiveWithoutUseAgnosticStrategies} U
- * @param {ResolvedDirectives_BlockedImports<T, U>} resolvedDirectives_blockedImports The blocked imports object, either for agnostic20 or for directive21.
- * @param {T} currentFileResolvedDirective The current file's "resolved" directive.
- * @param {U} importedFileResolvedDirective The imported file's "resolved" directive.
- * @returns `true` if the import is blocked, as established in respective `resolvedDirectives_blockedImports`.
+ * @param {ResolvedDirectives_BlockedImports<T, U>} resolvedDirectives_blockedImports $COMMENT#JSDOC#PARAMS#RESOLVEDDIRECTIVES_BLOCKEDIMPORTS
+ * @param {T} currentFileResolvedDirective $COMMENT#JSDOC#PARAMS#CURRENTFILERESOLVEDDIRECTIVEA
+ * @param {U} importedFileResolvedDirective $COMMENT#JSDOC#PARAMS#IMPORTEDFILERESOLVEDDIRECTIVE
+ * @returns $COMMENT#JSDOC#RETURNS#ISIMPORTBLOCKED
  */
 export const isImportBlocked = (
   // Note: "Blocked" here is preferred over "not allowed" because a specific message will be shared for each of the blocked situations, explaining their reasons and the solutions needed.
@@ -50,12 +50,12 @@ export const isImportBlocked = (
 /* makeIntroForSpecificViolationMessage */
 
 /**
- * Makes the intro for each specific import rule violation messages.
+ * $COMMENT#JSDOC#DEFINITIONS#MAKEINTROFORSPECIFICVIOLATIONMESSAGE
  * @template {ResolvedDirectiveWithoutUseAgnosticStrategies} T
  * @template {ResolvedDirectiveWithoutUseAgnosticStrategies} U
- * @param {T} currentFileResolvedDirective The current file's "resolved" directive.
- * @param {U} importedFileResolvedDirective The imported file's "resolved" directive.
- * @returns "[Current file 'resolved' modules] are not allowed to import [imported file 'resolved' modules]."
+ * @param {T} currentFileResolvedDirective $COMMENT#JSDOC#PARAMS#CURRENTFILERESOLVEDDIRECTIVEA
+ * @param {U} importedFileResolvedDirective $COMMENT#JSDOC#PARAMS#IMPORTEDFILERESOLVEDDIRECTIVE
+ * @returns $COMMENT#JSDOC#RETURNS#MAKEINTROFORSPECIFICVIOLATIONMESSAGE
  */
 export const makeIntroForSpecificViolationMessage = (
   currentFileResolvedDirective,
@@ -70,12 +70,12 @@ export const makeIntroForSpecificViolationMessage = (
 /* makeMessageFromCurrentFileResolvedDirective */
 
 /**
- * Lists in an message the "resolved" modules incompatible with a "resolved" module based on its "resolved" directive.
+ * $COMMENT#JSDOC#DEFINITIONS#MAKEMESSAGEFROMCURRENTFILERESOLVEDDIRECTIVE
  * @template {ResolvedDirectiveWithoutUseAgnosticStrategies} T
  * @template {ResolvedDirectiveWithoutUseAgnosticStrategies} U
- * @param {ResolvedDirectives_BlockedImports<T, U>} resolvedDirectives_blockedImports The blocked imports object, either for agnostic20 or for directive21.
- * @param {T} currentFileResolvedDirective The "resolved" directive of the "resolved" module.
- * @returns The message listing the incompatible "resolved" modules.
+ * @param {ResolvedDirectives_BlockedImports<T, U>} resolvedDirectives_blockedImports $COMMENT#JSDOC#PARAMS#RESOLVEDDIRECTIVES_BLOCKEDIMPORTS
+ * @param {T} currentFileResolvedDirective $COMMENT#JSDOC#PARAMS#CURRENTFILERESOLVEDDIRECTIVEB
+ * @returns $COMMENT#JSDOC#RETURNS#MAKEMESSAGEFROMCURRENTFILERESOLVEDDIRECTIVE
  */
 export const makeMessageFromCurrentFileResolvedDirective = (
   resolvedDirectives_blockedImports,
@@ -111,13 +111,13 @@ export const makeMessageFromCurrentFileResolvedDirective = (
 /* findSpecificViolationMessage */
 
 /**
- * Finds the `message` for the specific violation of "resolved" directives import rules based on `resolvedDirectives_blockedImports`.
+ * $COMMENT#JSDOC#DEFINITIONS#FINDSPECIFICVIOLATIONMESSAGE
  * @template {ResolvedDirectiveWithoutUseAgnosticStrategies} T
  * @template {ResolvedDirectiveWithoutUseAgnosticStrategies} U
- * @param {ResolvedDirectives_BlockedImports<T, U>} resolvedDirectives_blockedImports The blocked imports object, either for agnostic20 or for directive21.
- * @param {T} currentFileResolvedDirective The current file's "resolved" directive.
- * @param {U} importedFileResolvedDirective The imported file's "resolved" directive.
- * @returns The corresponding `message`.
+ * @param {ResolvedDirectives_BlockedImports<T, U>} resolvedDirectives_blockedImports $COMMENT#JSDOC#PARAMS#RESOLVEDDIRECTIVES_BLOCKEDIMPORTS
+ * @param {T} currentFileResolvedDirective $COMMENT#JSDOC#PARAMS#CURRENTFILERESOLVEDDIRECTIVEA
+ * @param {U} importedFileResolvedDirective $COMMENT#JSDOC#PARAMS#IMPORTEDFILERESOLVEDDIRECTIVE
+ * @returns $COMMENT#JSDOC#RETURNS#FINDSPECIFICVIOLATIONMESSAGE
  */
 export const findSpecificViolationMessage = (
   resolvedDirectives_blockedImports,

package/library/_commons/utilities/walk-ast.js

@@ -0,0 +1,46 @@
+/**
+ * @typedef {import("../../../types/_commons/typedefs.js").SourceCode} SourceCode
+ * @typedef {import("../../../types/_commons/typedefs.js").VisitorKeys} VisitorKeys
+ * @typedef {import("../../../types/_commons/typedefs.js").Node} Node
+ */
+
+/**
+ * Walks an AST with a given callback.
+ * @param {SourceCode} sourceCode
+ * @param {(node: Node, parent: Node | null) => void} callback
+ */
+export const walkAST = (sourceCode, callback) => {
+  const ast = sourceCode.ast;
+  const visitorKeys = sourceCode.visitorKeys;
+
+  visitNode(ast, null, visitorKeys, callback);
+};
+
+/**
+ * Recursively visits an AST node with a given callback.
+ * @param {Node} node
+ * @param {Node | null} parent
+ * @param {VisitorKeys} visitorKeys
+ * @param {(node: Node, parent: Node | null) => void} callback
+ */
+const visitNode = (node, parent, visitorKeys, callback) => {
+  callback(node, parent);
+
+  const keys = visitorKeys[node.type];
+  if (!keys) return;
+
+  for (const key of keys) {
+    const val = node[key];
+    if (!val) continue;
+
+    if (Array.isArray(val)) {
+      for (const child of val) {
+        if (child && typeof child.type === "string") {
+          visitNode(child, node, visitorKeys, callback);
+        }
+      }
+    } else if (val && typeof val.type === "string") {
+      visitNode(val, node, visitorKeys, callback);
+    }
+  }
+};

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

@@ -89,12 +89,12 @@ const SUGGEST_USE_AGNOSTIC =
   "If the module you're trying to import does not possess any server-side code however, please mark it with this plugin's own and eponymous 'use agnostic' directive to signal its compatibility across all environments.";
 
 /**
- * Makes a blockedImport object for the identified blocked import at hand.
+ * $COMMENT#JSDOC#DEFINITIONS#AGNOSTIC20#MAKEBLOCKEDIMPORT
  * @template {EffectiveDirective} T
  * @template {EffectiveDirective} U
- * @param {T} currentFileEffectiveDirective The current file's effective directive.
- * @param {U} importedFileEffectiveDirective The imported file's effective directive.
- * @returns The blockedImport object for the identified blocked import at hand.
+ * @param {T} currentFileEffectiveDirective $COMMENT#JSDOC#PARAMS#AGNOSTIC20#CURRENTFILEEFFECTIVEDIRECTIVE
+ * @param {U} importedFileEffectiveDirective $COMMENT#JSDOC#PARAMS#AGNOSTIC20#IMPORTEDFILEEFFECTIVEDIRECTIVE
+ * @returns $COMMENT#JSDOC#RETURNS#AGNOSTIC20#MAKEBLOCKEDIMPORT
  */
 export const makeBlockedImport = (
   currentFileEffectiveDirective,
@@ -114,12 +114,12 @@ export const makeBlockedImport = (
 };
 
 /**
- * Makes a blockedImport object for the identified blocked import at hand enhanced with the suggestion to use the `'use agnostic'` directive.
+ * $COMMENT#JSDOC#DEFINITIONS#AGNOSTIC20#MAKEBLOCKEDIMPORTSUGGESTINGUSEAGNOSTIC
  * @template {EffectiveDirective} T
  * @template {EffectiveDirective} U
- * @param {T} currentFileEffectiveDirective The current file's effective directive.
- * @param {U} importedFileEffectiveDirective The imported file's effective directive.
- * @returns The enhanced blockedImport object with the suggestion to use the `'use agnostic'` directive.
+ * @param {T} currentFileEffectiveDirective $COMMENT#JSDOC#PARAMS#AGNOSTIC20#CURRENTFILEEFFECTIVEDIRECTIVE
+ * @param {U} importedFileEffectiveDirective $COMMENT#JSDOC#PARAMS#AGNOSTIC20#IMPORTEDFILEEFFECTIVEDIRECTIVE
+ * @returns $COMMENT#JSDOC#RETURNS#AGNOSTIC20#MAKEBLOCKEDIMPORTSUGGESTINGUSEAGNOSTIC
  */
 const makeBlockedImportSuggestingUseAgnostic = (
   currentFileEffectiveDirective,
@@ -140,123 +140,123 @@ const makeBlockedImportSuggestingUseAgnostic = (
 
 export const effectiveDirectives_blockedImports = Object.freeze({
   [USE_SERVER_LOGICS]: Object.freeze([
-    // USE_SERVER_LOGICS allowed, because Server Logics can compose with one another.
-    // USE_SERVER_COMPONENTS allowed, because Server Components are OK to be composed with Server Logics as long as the Server Logics Module, by convention, does not export React components.
-    // USE_SERVER_FUNCTIONS allowed, because Server Functions, being able to import one another, can compose and do so via 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.)
+    // USE_SERVER_LOGICS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_SERVER_LOGICS#USE_SERVER_LOGICS
+    // USE_SERVER_COMPONENTS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_SERVER_LOGICS#USE_SERVER_COMPONENTS
+    // USE_SERVER_FUNCTIONS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_SERVER_LOGICS#USE_SERVER_FUNCTIONS
     makeBlockedImport(
       USE_SERVER_LOGICS,
       USE_CLIENT_LOGICS
-    ) /* Client Logics should never leak to the server. */,
+    ) /* $COMMENT#AGNOSTIC20#FORALIASVARIABLES#CLIENTNEVERSERVER */,
     makeBlockedImport(
       USE_SERVER_LOGICS,
       USE_CLIENT_COMPONENTS
-    ) /* Client Components cannot be tinkered with on the server. */,
-    // USE_AGNOSTIC_LOGICS allowed, because Agnostic Logics can run safely on the server just like they can on the client.
-    // USE_AGNOSTIC_COMPONENTS allowed, because Agnostic Components can be composed with Logics on the server just like they can on the client, as long at the Server Logics Module, by convention, does not export React components.
+    ) /* $COMMENT#AGNOSTIC20#USE_SERVER_LOGICS#USE_CLIENT_COMPONENTS */,
+    // USE_AGNOSTIC_LOGICS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#FORALIASVARIABLES#AGNOSTICCANSERVERCLIENT
+    // USE_AGNOSTIC_COMPONENTS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_SERVER_LOGICS#USE_AGNOSTIC_COMPONENTS
   ]),
   [USE_SERVER_COMPONENTS]: Object.freeze([
-    // USE_SERVER_LOGICS allowed, because Server Logics, being logic from the server, can safely support Server Components.
-    // USE_SERVER_COMPONENTS allowed, because Server Components can compose with one another, assuming thanks to the inclusion of the 'use agnostic' directive that they are actual Server Components.
-    // USE_SERVER_FUNCTIONS allowed, because Server Functions can be passed to imported Client Components within Server Components Modules, even though indeed Server Components Modules and Server Components can make their own Server Functions through inline `'use server'` directives.
+    // USE_SERVER_LOGICS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_SERVER_COMPONENTS#USE_SERVER_LOGICS
+    // USE_SERVER_COMPONENTS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_SERVER_COMPONENTS#USE_SERVER_COMPONENTS
+    // USE_SERVER_FUNCTIONS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_SERVER_COMPONENTS#USE_SERVER_FUNCTIONS
     makeBlockedImport(
       USE_SERVER_COMPONENTS,
       USE_CLIENT_LOGICS
-    ) /* Client Logics should never leak to the server. */,
-    // USE_CLIENT_COMPONENTS allowed, because Client Components can be nested inside Server Components either to wrap some of the tree with client state accessible through child Client Components and pass through Server Components or to create client boundaries when the root of the application is planted on the server.
-    // USE_AGNOSTIC_LOGICS allowed, because Agnostic Logics can run safely on the server just like they can on the client.
-    // USE_AGNOSTIC_COMPONENTS allowed, because Agnostic Components can render safely on the server just like they can on the client.
+    ) /* $COMMENT#AGNOSTIC20#FORALIASVARIABLES#CLIENTNEVERSERVER */,
+    // USE_CLIENT_COMPONENTS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_SERVER_COMPONENTS#USE_CLIENT_COMPONENTS
+    // USE_AGNOSTIC_LOGICS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#FORALIASVARIABLES#AGNOSTICCANSERVERCLIENT
+    // USE_AGNOSTIC_COMPONENTS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_SERVER_COMPONENTS#USE_AGNOSTIC_COMPONENTS
   ]),
   [USE_SERVER_FUNCTIONS]: Object.freeze([
-    // USE_SERVER_LOGICS allowed, because Server Logics, being logic from the server, can safely support Server Functions.
+    // USE_SERVER_LOGICS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_SERVER_FUNCTIONS#USE_SERVER_LOGICS
     makeBlockedImport(
       USE_SERVER_FUNCTIONS,
       USE_SERVER_COMPONENTS
-    ) /* Server Components aren't allowed because Server Functions have no business working with React Components. */,
-    // USE_SERVER_FUNCTIONS allowed, because Server Functions, even though they don't need to import one another and the same results can be generated via 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.)
+    ) /* $COMMENT#AGNOSTIC20#USE_SERVER_FUNCTIONS#USE_SERVER_COMPONENTS */,
+    // USE_SERVER_FUNCTIONS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_SERVER_FUNCTIONS#USE_SERVER_FUNCTIONS
     makeBlockedImport(
       USE_SERVER_FUNCTIONS,
       USE_CLIENT_LOGICS
-    ) /* Client Logics should never leak to the server. */,
+    ) /* $COMMENT#AGNOSTIC20#FORALIASVARIABLES#CLIENTNEVERSERVER */,
     makeBlockedImport(
       USE_SERVER_FUNCTIONS,
       USE_CLIENT_COMPONENTS
-    ) /* Client Components aren't allowed because Server Functions have no business working with React Components. */,
-    // USE_AGNOSTIC_LOGICS allowed, because Agnostic Logics can run safely on the server just like they can on the client.
+    ) /* $COMMENT#AGNOSTIC20#USE_SERVER_FUNCTIONS#USE_CLIENT_COMPONENTS */,
+    // USE_AGNOSTIC_LOGICS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#FORALIASVARIABLES#AGNOSTICCANSERVERCLIENT
     makeBlockedImport(
       USE_SERVER_FUNCTIONS,
       USE_AGNOSTIC_COMPONENTS
-    ) /* Agnostic Components aren't allowed because Server Functions have no business working with React Components. */,
+    ) /* $COMMENT#AGNOSTIC20#USE_SERVER_FUNCTIONS#USE_AGNOSTIC_COMPONENTS */,
   ]),
   [USE_CLIENT_LOGICS]: Object.freeze([
     makeBlockedImportSuggestingUseAgnostic(
       USE_CLIENT_LOGICS,
       USE_SERVER_LOGICS
-    ) /* Server Logics should never leak to the client. */,
+    ) /* $COMMENT#AGNOSTIC20#FORALIASVARIABLES#SERVERNEVERCLIENT */,
     makeBlockedImportSuggestingUseAgnostic(
       USE_CLIENT_LOGICS,
       USE_SERVER_COMPONENTS
-    ) /* Server Components cannot be tinkered with on the client. */,
-    // USE_SERVER_FUNCTIONS allowed, because Server Functions can technically be attached to Client Components that are being tinkered with within Client Logics Modules.
-    // USE_CLIENT_LOGICS allowed, because Client Logics can compose with one another.
-    // USE_CLIENT_COMPONENTS allowed, because Client Components are OK to be composed with Client Logics as long as the Client Logics Module, by convention, does not export React components.
-    // USE_AGNOSTIC_LOGICS allowed, because Agnostic Logics can run safely on the client just like they can on the server.
-    // USE_AGNOSTIC_COMPONENTS allowed, because Agnostic Components can be composed with Logics on the client just like they can on the server, as long as the Client Logics Module, by convention, does not export React components.
+    ) /* $COMMENT#AGNOSTIC20#USE_CLIENT_LOGICS#USE_SERVER_COMPONENTS */,
+    // USE_SERVER_FUNCTIONS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_CLIENT_LOGICS#USE_SERVER_FUNCTIONS
+    // USE_CLIENT_LOGICS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_CLIENT_LOGICS#USE_CLIENT_LOGICS
+    // USE_CLIENT_COMPONENTS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_CLIENT_LOGICS#USE_CLIENT_COMPONENTS
+    // USE_AGNOSTIC_LOGICS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#FORALIASVARIABLES#AGNOSTICCANCLIENTSERVER
+    // USE_AGNOSTIC_COMPONENTS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_CLIENT_LOGICS#USE_AGNOSTIC_COMPONENTS
   ]),
   [USE_CLIENT_COMPONENTS]: Object.freeze([
     makeBlockedImportSuggestingUseAgnostic(
       USE_CLIENT_LOGICS,
       USE_SERVER_LOGICS
-    ) /* Server Logics should never leak to the client. */,
+    ) /* $COMMENT#AGNOSTIC20#FORALIASVARIABLES#SERVERNEVERCLIENT */,
     makeBlockedImportSuggestingUseAgnostic(
       USE_CLIENT_LOGICS,
       USE_SERVER_COMPONENTS
-    ) /* Server Components cannot be tinkered with on the client. */,
-    // USE_SERVER_FUNCTIONS allowed, because Server Functions can specifically be triggered by Client Components.
-    // USE_CLIENT_LOGICS allowed, because Client Logics, being logic from the client, can safely support Client Components.
-    // USE_CLIENT_COMPONENTS allowed, because Client Components can compose with one another.
-    // USE_AGNOSTIC_LOGICS allowed, because Agnostic Logics can run safely on the client just like they can on the server.
-    // USE_AGNOSTIC_COMPONENTS allowed, because Agnostic Components can render safely on the client just like they can on the server.
+    ) /* $COMMENT#AGNOSTIC20#USE_CLIENT_LOGICS#USE_SERVER_COMPONENTS */,
+    // USE_SERVER_FUNCTIONS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_CLIENT_COMPONENTS#USE_SERVER_FUNCTIONS
+    // USE_CLIENT_LOGICS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_CLIENT_COMPONENTS#USE_CLIENT_LOGICS
+    // USE_CLIENT_COMPONENTS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_CLIENT_COMPONENTS#USE_CLIENT_COMPONENTS
+    // USE_AGNOSTIC_LOGICS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#FORALIASVARIABLES#AGNOSTICCANCLIENTSERVER
+    // USE_AGNOSTIC_COMPONENTS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_CLIENT_COMPONENTS#USE_AGNOSTIC_COMPONENTS
   ]),
   [USE_AGNOSTIC_LOGICS]: Object.freeze([
     makeBlockedImportSuggestingUseAgnostic(
       USE_AGNOSTIC_LOGICS,
       USE_SERVER_LOGICS
-    ) /* Server Logics cannot run on both the server and the client. */,
+    ) /* $COMMENT#AGNOSTIC20#FORALIASVARIABLES#SERVERLOGICSCANTBOTH */,
     makeBlockedImportSuggestingUseAgnostic(
       USE_AGNOSTIC_LOGICS,
       USE_SERVER_COMPONENTS
-    ) /* Server Components cannot be tinkered with on both the server and the client. */,
+    ) /* $COMMENT#AGNOSTIC20#USE_AGNOSTIC_LOGICS#USE_SERVER_COMPONENTS */,
     makeBlockedImport(
       USE_AGNOSTIC_LOGICS,
       USE_SERVER_FUNCTIONS
-    ) /* 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. */,
+    ) /* $COMMENT#AGNOSTIC20#USE_AGNOSTIC_LOGICS#USE_SERVER_FUNCTIONS */,
     makeBlockedImport(
       USE_AGNOSTIC_LOGICS,
       USE_CLIENT_LOGICS
-    ) /* Client Logics cannot run on both the server and the client. */,
+    ) /* $COMMENT#AGNOSTIC20#FORALIASVARIABLES#CLIENTLOGICSCANTBOTH */,
     makeBlockedImport(
       USE_AGNOSTIC_LOGICS,
       USE_CLIENT_COMPONENTS
-    ) /* Client Components cannot be tinkered with on both the server and the client. */,
-    // USE_AGNOSTIC_LOGICS allowed, because Agnostic Logics can compose with one another.
-    // USE_AGNOSTIC_COMPONENTS allowed, because Agnostic Components can be composed with Logics agnostically as long as the Agnostic Logics Module, by convention, does not export React components.
+    ) /* $COMMENT#AGNOSTIC20#USE_AGNOSTIC_LOGICS#USE_CLIENT_COMPONENTS */,
+    // USE_AGNOSTIC_LOGICS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_AGNOSTIC_LOGICS#USE_AGNOSTIC_LOGICS
+    // USE_AGNOSTIC_COMPONENTS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_AGNOSTIC_LOGICS#USE_AGNOSTIC_COMPONENTS
   ]),
   [USE_AGNOSTIC_COMPONENTS]: Object.freeze([
     makeBlockedImportSuggestingUseAgnostic(
       USE_AGNOSTIC_COMPONENTS,
       USE_SERVER_LOGICS
-    ) /* Server Logics cannot run on both the server and the client. */,
+    ) /* $COMMENT#AGNOSTIC20#FORALIASVARIABLES#SERVERLOGICSCANTBOTH */,
     makeBlockedImportSuggestingUseAgnostic(
       USE_AGNOSTIC_COMPONENTS,
       USE_SERVER_COMPONENTS
-    ) /* Server Components, unlike 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_SERVER_FUNCTIONS allowed, because Server Functions can be passed to Client Components as props when Client Components are also legally imported into Agnostic Components Modules.
+    ) /* $COMMENT#AGNOSTIC20#USE_AGNOSTIC_COMPONENTS#USE_SERVER_COMPONENTS */,
+    // USE_SERVER_FUNCTIONS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_AGNOSTIC_COMPONENTS#USE_SERVER_FUNCTIONS
     makeBlockedImport(
       USE_AGNOSTIC_COMPONENTS,
       USE_CLIENT_LOGICS
-    ) /* Client Logics cannot run on both the server and the client. */,
-    // USE_CLIENT_COMPONENTS allowed, because Client Components can be nested inside Agnostic Components either to wrap some of the tree with client state accessible through child Client Components and pass through Server Components — if still on the Server Tree — or to create client boundaries when the root of the application is planted on the server.
-    // USE_AGNOSTIC_LOGICS allowed, because Agnostic Logics, being environment-agnostic logic, can safely support Agnostic Components.
-    // USE_AGNOSTIC_COMPONENTS allowed, because Agnostic Components can compose with one another.
+    ) /* $COMMENT#AGNOSTIC20#FORALIASVARIABLES#CLIENTLOGICSCANTBOTH */,
+    // USE_CLIENT_COMPONENTS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_AGNOSTIC_COMPONENTS#USE_CLIENT_COMPONENTS
+    // USE_AGNOSTIC_LOGICS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_AGNOSTIC_COMPONENTS#USE_AGNOSTIC_LOGICS
+    // USE_AGNOSTIC_COMPONENTS $COMMENT#AGNOSTIC20#FORCOMPOSEDVARIABLES#ALLOWEDBECAUSE $COMMENT#AGNOSTIC20#USE_AGNOSTIC_COMPONENTS#USE_AGNOSTIC_COMPONENTS
   ]),
 });

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

@@ -40,9 +40,9 @@ import {
 /* currentFileFlow */
 
 /**
- * The flow that begins the import rules enforcement rule, retrieving the effective directive of the current file before comparing it to upcoming effective 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 `currentFileEffectiveDirective`.
+ * $COMMENT#JSDOC#DEFINITIONS#AGNOSTIC20#CURRENTFILEFLOW
+ * @param {Context} context $COMMENT#JSDOC#PARAMS#CONTEXTB
+ * @returns $COMMENT#JSDOC#RETURNS#AGNOSTIC20#CURRENTFILEFLOW
  */
 export const currentFileFlow = (context) => {
   const skipTrue = { ...skip, currentFileEffectiveDirective: undefined };
@@ -95,10 +95,10 @@ export const currentFileFlow = (context) => {
 /* importedFileFlow */
 
 /**
- * The flow that is shared between import and re-export traversals to obtain the import file's effective 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 `importedFileEffectiveDirective`.
+ * $COMMENT#JSDOC#DEFINITIONS#AGNOSTIC20#IMPORTEDFILEFLOW
+ * @param {Context} context $COMMENT#JSDOC#PARAMS#CONTEXTB
+ * @param {ImportDeclaration} node $COMMENT#JSDOC#PARAMS#NODE
+ * @returns $COMMENT#JSDOC#RETURNS#AGNOSTIC20#IMPORTEDFILEFLOW
  */
 const importedFileFlow = (context, node) => {
   const skipTrue = { ...skip, importedFileEffectiveDirective: undefined };
@@ -146,11 +146,11 @@ const importedFileFlow = (context, node) => {
 
 /* 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 {EffectiveDirective} currentFileEffectiveDirective The current file's effective 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 {EffectiveDirective} currentFileEffectiveDirective $COMMENT#JSDOC#PARAMS#AGNOSTIC20#CURRENTFILEEFFECTIVEDIRECTIVE
+ * @returns $COMMENT#JSDOC#FORALIASVARIABLES#FLOWRETURNSEARLY
  */
 export const importsFlow = (context, node, currentFileEffectiveDirective) => {
   // does not operate on `import type`
@@ -186,11 +186,11 @@ export const importsFlow = (context, node, currentFileEffectiveDirective) => {
 
 /* reExportsFlow */
 
-/** The full flow for export traversals, shared between `ExportNamedDeclaration` and `ExportAllDeclaration`, to ensure same effective directive re-exports.
- * @param {Context} context The ESLint rule's `context` object.
- * @param {ExportNamedDeclaration | ExportAllDeclaration} node The ESLint `node` of the rule's current traversal.
- * @param {EffectiveDirective} currentFileEffectiveDirective The current file's effective directive.
- * @returns Early if the flow needs to be interrupted.
+/** $COMMENT#JSDOC#DEFINITIONS#AGNOSTIC20#REEXPORTSFLOW
+ * @param {Context} context $COMMENT#JSDOC#PARAMS#CONTEXTB
+ * @param {ExportNamedDeclaration | ExportAllDeclaration} node $COMMENT#JSDOC#PARAMS#NODE
+ * @param {EffectiveDirective} currentFileEffectiveDirective $COMMENT#JSDOC#PARAMS#AGNOSTIC20#CURRENTFILEEFFECTIVEDIRECTIVE
+ * @returns $COMMENT#JSDOC#FORALIASVARIABLES#FLOWRETURNSEARLY
  */
 export const reExportsFlow = (context, node, currentFileEffectiveDirective) => {
   // does not operate on `export type`

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

@@ -28,13 +28,13 @@ import {
 /* getDirectiveFromModule */
 
 /**
- * Gets the directive of a module from its Abstract Syntax Tree.
- * - `null` denotes a server-by-default module, ideally a Server Module.
- * - `'use server'` denotes a Server Functions Module.
- * - `'use client'` denotes a Client Module.
- * - `'use agnostic'` denotes an Agnostic Module (formerly Shared Module).
- * @param {AST} ast The module's AST (Abstract Syntax Tree).
- * @returns The directive, or lack thereof via `null`. The lack of a directive is considered server-by-default.
+ * $COMMENT#JSDOC#DEFINITIONS#AGNOSTIC20#GETDIRECTIVEFROMMODULE
+ * - $COMMENT#JSDOC#DETAILS#AGNOSTIC20#NULLDIRECTIVE
+ * - $COMMENT#JSDOC#DETAILS#AGNOSTIC20#USESERVER
+ * - $COMMENT#JSDOC#DETAILS#AGNOSTIC20#USECLIENT
+ * - $COMMENT#JSDOC#DETAILS#AGNOSTIC20#USEAGNOSTIC
+ * @param {AST} ast $COMMENT#JSDOC#PARAMS#AGNOSTIC20#AST
+ * @returns $COMMENT#JSDOC#RETURNS#AGNOSTIC20#GETDIRECTIVEFROMMODULE
  */
 export const getDirectiveFromModule = (ast) => {
   // the AST body to check for the top-of-the-file directive
@@ -63,13 +63,13 @@ export const getDirectiveFromModule = (ast) => {
 /* getDirectiveFromCurrentModule */
 
 /**
- * Gets the directive of the current module.
- * - `null` denotes a server-by-default module, ideally a Server Module.
- * - `'use server'` denotes a Server Functions Module.
- * - `'use client'` denotes a Client Module.
- * - `'use agnostic'` denotes an Agnostic Module (formerly Shared Module).
- * @param {Context} context The ESLint rule's `context` object.
- * @returns The directive, or lack thereof via `null`. The lack of a directive is considered server-by-default.
+ * $COMMENT#JSDOC#DEFINITIONS#AGNOSTIC20#GETDIRECTIVEFROMCURRENTMODULE
+ * - $COMMENT#JSDOC#DETAILS#AGNOSTIC20#NULLDIRECTIVE
+ * - $COMMENT#JSDOC#DETAILS#AGNOSTIC20#USESERVER
+ * - $COMMENT#JSDOC#DETAILS#AGNOSTIC20#USECLIENT
+ * - $COMMENT#JSDOC#DETAILS#AGNOSTIC20#USEAGNOSTIC
+ * @param {Context} context $COMMENT#JSDOC#PARAMS#CONTEXTB
+ * @returns $COMMENT#JSDOC#RETURNS#AGNOSTIC20#GETDIRECTIVEFROMMODULE
  */
 export const getDirectiveFromCurrentModule = (context) => {
   // the AST of the current module
@@ -81,13 +81,13 @@ export const getDirectiveFromCurrentModule = (context) => {
 /* getDirectiveFromImportedModule */
 
 /**
- * Gets the directive of the imported module.
- * - `null` denotes a server-by-default module, ideally a Server Module.
- * - `'use server'` denotes a Server Functions Module.
- * - `'use client'` denotes a Client Module.
- * - `'use agnostic'` denotes an Agnostic Module (formerly Shared Module).
- * @param {string} resolvedPath The resolved path of the imported module.
- * @returns The directive, or lack thereof via `null`. The lack of a directive is considered server-by-default.
+ * $COMMENT#JSDOC#DEFINITIONS#AGNOSTIC20#GETDIRECTIVEFROMIMPORTEDMODULE
+ * - $COMMENT#JSDOC#DETAILS#AGNOSTIC20#NULLDIRECTIVE
+ * - $COMMENT#JSDOC#DETAILS#AGNOSTIC20#USESERVER
+ * - $COMMENT#JSDOC#DETAILS#AGNOSTIC20#USECLIENT
+ * - $COMMENT#JSDOC#DETAILS#AGNOSTIC20#USEAGNOSTIC
+ * @param {string} resolvedPath $COMMENT#JSDOC#PARAMS#RESOLVEDPATH
+ * @returns $COMMENT#JSDOC#RETURNS#AGNOSTIC20#GETDIRECTIVEFROMMODULE
  */
 export const getDirectiveFromImportedModule = (resolvedPath) => {
   // the AST of the imported module
@@ -99,17 +99,17 @@ export const getDirectiveFromImportedModule = (resolvedPath) => {
 /* getEffectiveDirective */
 
 /**
- * Gets the effective directive of a module, based on the combination of its directive (or lack thereof) and its extension (depending on whether it ends with 'x' for JSX).
- * - `'use server logics'` denotes a Server Logics Module.
- * - `'use server components'` denotes a Server Components Module.
- * - `'use server functions'` denotes a Server Functions Module.
- * - `'use client logics'` denotes a Client Logics Module.
- * - `'use client components'` denotes a Client Components Module.
- * - `'use agnostic logics'` denotes an Agnostic Logics Module.
- * - `'use agnostic components'` denotes an Agnostic Components Module.
- * @param {Directive | NoDirective} directive The directive as written on top of the file (`"no directive"` if no valid directive).
- * @param {Extension} extension The JavaScript (TypeScript) extension of the file.
- * @returns The effective directive, from which imports rules are applied.
+ * $COMMENT#JSDOC#DEFINITIONS#AGNOSTIC20#GETEFFECTIVEDIRECTIVE
+ * - $COMMENT#JSDOC#DETAILS#AGNOSTIC20#USESERVERLOGICS
+ * - $COMMENT#JSDOC#DETAILS#AGNOSTIC20#USESERVERCOMPONENTS
+ * - $COMMENT#JSDOC#DETAILS#AGNOSTIC20#USESERVERFUNCTIONS
+ * - $COMMENT#JSDOC#DETAILS#AGNOSTIC20#USECLIENTLOGICS
+ * - $COMMENT#JSDOC#DETAILS#AGNOSTIC20#USECLIENTCOMPONENTS
+ * - $COMMENT#JSDOC#DETAILS#AGNOSTIC20#USEAGNOSTICLOGICS
+ * - $COMMENT#JSDOC#DETAILS#AGNOSTIC20#USEAGNOSTICCOMPONENTS
+ * @param {Directive | NoDirective} directive $COMMENT#JSDOC#PARAMS#AGNOSTIC20#DIRECTIVE
+ * @param {Extension} extension $COMMENT#JSDOC#PARAMS#EXTENSION
+ * @returns $COMMENT#JSDOC#RETURNS#AGNOSTIC20#GETEFFECTIVEDIRECTIVE
  */
 export const getEffectiveDirective = (directive, extension) => {
   const moduleKind = extension.endsWith("x")
@@ -124,10 +124,10 @@ export const getEffectiveDirective = (directive, extension) => {
 /* isImportBlocked */
 
 /**
- * Returns a boolean deciding if an imported file's effective directive is incompatible with the current file's effective directive.
- * @param {EffectiveDirective} currentFileEffectiveDirective The current file's effective directive.
- * @param {EffectiveDirective} importedFileEffectiveDirective The imported file's effective directive.
- * @returns `true` if the import is blocked, as established in `effectiveDirectives_BlockedImports`.
+ * $COMMENT#JSDOC#DEFINITIONS#AGNOSTIC20#ISIMPORTBLOCKED
+ * @param {EffectiveDirective} currentFileEffectiveDirective $COMMENT#JSDOC#PARAMS#AGNOSTIC20#CURRENTFILEEFFECTIVEDIRECTIVE
+ * @param {EffectiveDirective} importedFileEffectiveDirective $COMMENT#JSDOC#PARAMS#AGNOSTIC20#IMPORTEDFILEEFFECTIVEDIRECTIVE
+ * @returns $COMMENT#JSDOC#RETURNS#AGNOSTIC20#ISIMPORTBLOCKED
  */
 export const isImportBlocked = (
   currentFileEffectiveDirective,
@@ -142,9 +142,9 @@ export const isImportBlocked = (
 /* makeMessageFromCurrentFileEffectiveDirective */
 
 /**
- * Lists in an message the effective modules incompatible with a effective module based on its effective directive.
- * @param {EffectiveDirective} effectiveDirective The effective directive of the effective module.
- * @returns The message listing the incompatible effective modules.
+ * $COMMENT#JSDOC#DEFINITIONS#AGNOSTIC20#MAKEMESSAGEFROMCURRENTFILEEFFECTIVEDIRECTIVE
+ * @param {EffectiveDirective} effectiveDirective $COMMENT#JSDOC#PARAMS#AGNOSTIC20#EFFECTIVEDIRECTIVE
+ * @returns $COMMENT#JSDOC#RETURNS#AGNOSTIC20#MAKEMESSAGEFROMCURRENTFILEEFFECTIVEDIRECTIVE
  */
 export const makeMessageFromCurrentFileEffectiveDirective = (
   effectiveDirective
@@ -157,10 +157,10 @@ export const makeMessageFromCurrentFileEffectiveDirective = (
 /* findSpecificViolationMessage */
 
 /**
- * Finds the `message` for the specific violation of effective directives import rules based on `effectiveDirectives_BlockedImports`.
- * @param {EffectiveDirective} currentFileEffectiveDirective The current file's effective directive.
- * @param {EffectiveDirective} importedFileEffectiveDirective The imported file's effective directive.
- * @returns The corresponding `message`.
+ * $COMMENT#JSDOC#DEFINITIONS#AGNOSTIC20#FINDSPECIFICVIOLATIONMESSAGE
+ * @param {EffectiveDirective} currentFileEffectiveDirective $COMMENT#JSDOC#PARAMS#AGNOSTIC20#CURRENTFILEEFFECTIVEDIRECTIVE
+ * @param {EffectiveDirective} importedFileEffectiveDirective $COMMENT#JSDOC#PARAMS#AGNOSTIC20#IMPORTEDFILEEFFECTIVEDIRECTIVE
+ * @returns $COMMENT#JSDOC#RETURNS#FINDSPECIFICVIOLATIONMESSAGE
  */
 export const findSpecificViolationMessage = (
   currentFileEffectiveDirective,

package/library/agnostic20/config.js

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